NetBird Python Client (Unofficial)

Unofficial Python client library for the NetBird API. Provides complete access to all NetBird API resources with a simple, intuitive interface.

⚠️ Disclaimer: This is an unofficial, community-maintained client library. It is not affiliated with, endorsed by, or officially supported by NetBird or the NetBird team. For official NetBird tools and support, please visit netbird.io.

This client follows the same upstream schemas as the official NetBird REST APIs, ensuring full compatibility and consistency with the NetBird ecosystem.

Features

• ✅ Full API Parity - 30+ resources covering core, cloud, and EDR endpoints
• ✅ Cloud & Self-Hosted - Works with NetBird Cloud and self-hosted instances
• ✅ Forward-Compatible - extra="allow" on all models accepts future API fields gracefully
• ✅ Upstream Schema Compliance - Follows official NetBird REST API schemas exactly
• ✅ Dictionary Responses - Clean dictionary responses for easy data access
• ✅ Type Safety - Pydantic models for input validation, dictionaries for responses
• ✅ Network Visualization - Built-in diagram generation (Mermaid, Graphviz, Python Diagrams)
• ✅ Modern Python - Built for Python 3.10+ (supports 3.10-3.14)
• ✅ Comprehensive Error Handling - Detailed exception classes for different error types
• ✅ 88% Test Coverage - 364 unit tests covering all resources
• ✅ PyPI Ready - Easy installation and distribution
• ✅ MCP Server - 25 tools exposing NetBird operations to AI assistants via Model Context Protocol

Supported Resources

Core Resources

Resource	Description	Key Methods
Accounts	Account management and settings	List, Update, Delete
Users	User lifecycle management	CRUD, Approve, Reject, Invites, Password
Tokens	API token management	CRUD operations
Peers	Network peer management	CRUD, Temporary Access, Jobs
Setup Keys	Peer setup key management	CRUD operations
Groups	Peer group management	CRUD operations
Networks	Network and resource management	CRUD + Resources/Routers
Policies	Access control policies	CRUD operations
Routes	Network routing (deprecated)	CRUD (use Networks instead)
DNS	DNS nameserver groups	CRUD + Settings
DNS Zones	Custom DNS zones and records	Zone CRUD + Record CRUD
Events	Audit and traffic events	Audit, Traffic, Proxy events
Posture Checks	Device compliance verification	CRUD operations
Geo Locations	Geographic data	Countries, Cities
Identity Providers	OAuth2/OIDC providers	CRUD operations
Instance	Instance management	Status, Version, Setup

Cloud Resources (client.cloud.*)

Resource	Description	Key Methods
Services	Reverse proxy services	CRUD + Domain management
Ingress	Ingress port allocation	Port + Peer management
EDR Peers	EDR peer bypass	Bypass, List, Revoke
EDR Falcon	CrowdStrike Falcon	Get, Create, Update, Delete
EDR Huntress	Huntress integration	Get, Create, Update, Delete
EDR Intune	Microsoft Intune	Get, Create, Update, Delete
EDR SentinelOne	SentinelOne integration	Get, Create, Update, Delete
MSP	Multi-tenant management	Tenants CRUD + Users/Peers
Invoices	Billing invoices	List, PDF, CSV
Usage	Billing usage stats	Get usage
Event Streaming	Event streaming integrations	CRUD operations
IDP/SCIM	SCIM identity providers	CRUD + Token + Logs

Installation

pip install netbird

Quick Start

from netbird import APIClient

# Initialize the client
client = APIClient(
    host="api.netbird.io",  # or "netbird.yourcompany.com" for self-hosted
    api_token="your-api-token-here"
)

# List all peers
peers = client.peers.list()
print(f"Found {len(peers)} peers")

# Get current user
user = client.users.get_current()
print(f"Logged in as: {user['name']}")

# Create a new group
from netbird.models import GroupCreate
group_data = GroupCreate(
    name="My Team",
    peers=["peer-1", "peer-2"]
)
group = client.groups.create(group_data)
print(f"Created group: {group['name']}")

# Access cloud-only resources (NetBird Cloud only)
usage = client.cloud.usage.get()
print(f"Active peers: {usage['active_peers']}")

# EDR integrations
falcon_config = client.cloud.edr.falcon.get()

Authentication

NetBird uses token-based authentication with API access tokens:

client = APIClient(
    host="your-netbird-host.com",  # e.g., "api.netbird.io" for cloud
    api_token="your-api-token"
)

You can get your API token from:

• NetBird Cloud: Dashboard → Settings → API Tokens
• Self-hosted: Your NetBird management interface

Self-Hosted NetBird

client = APIClient(
    host="netbird.yourcompany.com:33073",
    api_token="your-token"
)

Examples

User Management

from netbird.models import UserCreate, UserRole

# Create a new user
user_data = UserCreate(
    email="user@company.com",
    name="New User",
    role=UserRole.USER,
    auto_groups=["group-default"]
)
user = client.users.create(user_data)
print(f"Created user: {user['name']} ({user['email']})")

# Update user role
from netbird.models import UserUpdate
update_data = UserUpdate(role=UserRole.ADMIN)
updated_user = client.users.update(user['id'], update_data)
print(f"Updated user role to: {updated_user['role']}")

Network Management

from netbird.models import NetworkCreate, PolicyCreate, PolicyRule

# Create a network
network_data = NetworkCreate(
    name="My Network",
    description="Network environment"
)
network = client.networks.create(network_data)
print(f"Created network: {network['name']}")

# Create access policy
rule = PolicyRule(
    name="Allow Access",
    action="accept",
    protocol="tcp", 
    ports=["22"],
    sources=["source-group"],
    destinations=["destination-group"]
)
policy_data = PolicyCreate(
    name="Access Policy",
    rules=[rule]
)
policy = client.policies.create(policy_data)
print(f"Created policy: {policy['name']}")

Setup Key Management

from netbird.models import SetupKeyCreate

# Create a reusable setup key
key_data = SetupKeyCreate(
    name="Environment Setup",
    type="reusable",
    expires_in=86400,  # 24 hours
    usage_limit=10,
    auto_groups=["default-group"]
)
setup_key = client.setup_keys.create(key_data)
print(f"Setup key: {setup_key['key']}")
print(f"Key valid: {setup_key['valid']}")

Event Monitoring

# Get audit events
audit_events = client.events.get_audit_events()
for event in audit_events[-10:]:  # Last 10 events
    print(f"{event['timestamp']}: {event['activity']}")
    if event.get('initiator_name'):
        print(f"  Initiated by: {event['initiator_name']}")

# Get network traffic events (cloud-only)
traffic_events = client.events.get_network_traffic_events(
    protocol="tcp",
    page_size=100
)
for traffic in traffic_events[:5]:
    print(f"Traffic: {traffic['source_ip']} -> {traffic['destination_ip']}")

Network Visualization

The NetBird Python client includes powerful network visualization capabilities that can generate topology diagrams in multiple formats:

Generate Network Maps

from netbird import APIClient
from netbird.network_map import generate_full_network_map

# Initialize client
client = APIClient(host="your-netbird-host.com", api_token="your-token")

# Generate enriched network data
networks = generate_full_network_map(client)

# Access enriched data
for network in networks:
    print(f"Network: {network['name']}")
    for resource in network.get('resources', []):
        print(f"  Resource: {resource['name']} - {resource['address']}")
    for policy in network.get('policies', []):
        print(f"  Policy: {policy['name']}")

Topology Visualization

from netbird.network_map import get_network_topology_data

# Get optimized topology data for visualization
topology = get_network_topology_data(client, optimize_connections=True)

print(f"Found {len(topology['all_source_groups'])} source groups")
print(f"Found {len(topology['group_connections'])} group connections")
print(f"Found {len(topology['direct_connections'])} direct connections")

Diagram Generation

Generate visual network topology diagrams directly from the client:

from netbird import APIClient

# Initialize client
client = APIClient(host="your-netbird-host.com", api_token="your-token")

# Generate Mermaid diagram (default, GitHub/GitLab compatible)
mermaid_content = client.generate_diagram(format="mermaid")
print(mermaid_content)

# Generate Graphviz diagram (PNG, SVG, PDF)
client.generate_diagram(format="graphviz", output_file="my_network")

# Generate Python Diagrams (PNG)
client.generate_diagram(format="diagrams", output_file="network_topology")

# Customize what to include
client.generate_diagram(
    format="mermaid",
    include_routers=True,
    include_policies=True, 
    include_resources=True,
    output_file="complete_network"
)

Supported Diagram Formats

Format	Output Files	Best For
Mermaid	.mmd, .md	GitHub/GitLab documentation, web viewing
Graphviz	.png, .svg, .pdf, .dot	High-quality publications, presentations
Diagrams	.png	Code documentation, architecture diagrams

Diagram Features

• Source Groups: Visual representation of user groups with distinct colors
• Networks & Resources: Hierarchical network structure with resource details
• Policy Connections:
  • 🟢 Group-based access (dashed lines)
  • 🔵 Direct resource access (solid lines)
• Optimized Layout: Merged connections to reduce visual complexity
• Rich Information: Resource addresses, types, and group memberships

Installation for Diagrams

# For Graphviz diagrams
pip install graphviz

# For Python Diagrams
pip install diagrams

# Mermaid requires no additional dependencies

Error Handling

The client provides specific exception types for different error conditions:

from netbird.exceptions import (
    NetBirdAPIError,
    NetBirdAuthenticationError,
    NetBirdNotFoundError,
    NetBirdRateLimitError,
    NetBirdServerError,
    NetBirdValidationError,
)

try:
    user = client.users.get("invalid-user-id")
except NetBirdNotFoundError:
    print("User not found")
except NetBirdAuthenticationError:
    print("Invalid API token")
except NetBirdRateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except NetBirdAPIError as e:
    print(f"API error: {e.message}")

Configuration Options

client = APIClient(
    host="your-netbird-host.com",  # Your NetBird API host
    api_token="your-token",
    timeout=30.0,           # Request timeout in seconds (default: 30)
    base_path="/api"        # API base path (default: "/api")
)

MCP Server (AI Assistant Integration)

The NetBird Python client includes a built-in Model Context Protocol (MCP) server, exposing 25 NetBird management tools to AI assistants like Claude Desktop.

Installation

pip install "netbird[mcp]"

Configuration

Set environment variables before starting the server:

export NETBIRD_HOST="api.netbird.io"         # or your self-hosted host
export NETBIRD_API_TOKEN="your-api-token"

Claude Code (CLI) Setup

claude mcp add netbird \
  -e NETBIRD_HOST=api.netbird.io \
  -e NETBIRD_API_TOKEN=your-api-token \
  -- netbird-mcp

Restart Claude Code. Verify with:

claude mcp list   # Should show: netbird: ... ✓ Connected

Claude Desktop Setup

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "netbird": {
      "command": "netbird-mcp",
      "env": {
        "NETBIRD_HOST": "api.netbird.io",
        "NETBIRD_API_TOKEN": "your-api-token"
      }
    }
  }
}

Restart Claude Desktop. You should see the hammer icon in the chat input confirming tools are loaded.

Usage

Once connected, ask Claude to manage your NetBird network in natural language:

• "List all peers and show their connection status"
• "Create a policy allowing the DevOps group to SSH into the Servers group"
• "Generate a Mermaid diagram of the current network topology"
• "Create a setup key for onboarding the new office location"

Available MCP Tools

Category	Tools
Account	get_account
Users	get_current_user, list_users
Peers	list_peers, get_peer, update_peer, delete_peer, get_peer_accessible_peers
Groups	list_groups, get_group, create_group, update_group, delete_group
Policies	list_policies, create_policy, delete_policy
Networks	list_networks, get_network
Setup Keys	list_setup_keys, create_setup_key
DNS	list_nameservers, get_dns_settings
Posture Checks	list_posture_checks
Audit	get_audit_events
Diagrams	generate_network_diagram

Running the Server Manually

NETBIRD_HOST=api.netbird.io NETBIRD_API_TOKEN=your-token netbird-mcp

Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/drtinkerer/netbird-python-client.git
cd netbird-python-client

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run type checking
mypy src/

# Format code
black src/ tests/
isort src/ tests/

# Run linting
flake8 src/ tests/

Testing & Coverage

Test Statistics

• Total Tests: 364 unit tests
• Coverage: 88% (2,045 statements)
• All models and resources: 100% coverage

Coverage by Module

Module	Coverage
Models (core + cloud)	100%
Resources (core + cloud)	100%
Auth / Exceptions	100%
Cloud Namespace	88%
Network Map	98%
Client Core	47% (diagram generation untested)

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=src/netbird --cov-report=html

# Run specific test categories
pytest tests/unit/              # Core resource tests
pytest tests/unit/cloud/        # Cloud resource tests

Response Format

The NetBird Python client provides clean and intuitive API responses:

• Input validation: Uses Pydantic models for type safety and validation
• API responses: Returns standard Python dictionaries for easy access
• Familiar patterns: Simple dictionary-based responses

# Input: Type-safe Pydantic models
user_data = UserCreate(email="john@example.com", name="John Doe")

# Output: Standard Python dictionaries
user = client.users.create(user_data)
print(user['name'])          # Access like a dictionary
print(user['email'])         # Easy dictionary access
print(user.get('role'))      # Safe access with .get()

Interactive Demo

Explore the client with our Jupyter notebook demo:

# Install Jupyter if you haven't already
pip install jupyter

# Start the demo notebook
jupyter notebook netbird_demo.ipynb

The demo notebook shows real usage examples for all API resources.

Documentation

• Full Documentation - Comprehensive Sphinx docs with API reference, user guides, and examples
• Jupyter Demo - Interactive demonstration of all features
• Integration Tests - Real API usage examples
• Unit Tests - Complete test coverage examples
• NetBird Documentation - Official NetBird docs

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to your branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer & Legal

This is an unofficial, community-maintained client library.

• ❌ Not official: This library is NOT affiliated with, endorsed by, or officially supported by NetBird or the NetBird team
• ❌ No warranty: This software is provided "as is" without warranty of any kind
• ❌ No official support: For official NetBird support, please contact NetBird directly
• ✅ Open source: This is a community effort to provide Python developers with NetBird API access
• ✅ Best effort compatibility: We strive to maintain compatibility with NetBird's official API

NetBird is a trademark of NetBird. This project is not endorsed by or affiliated with NetBird.

For official NetBird tools, documentation, and support:

• Official Website: netbird.io
• Official Documentation: docs.netbird.io
• Official GitHub: github.com/netbirdio/netbird

Support

• GitHub Issues: Report bugs or request features
• NetBird Community: Join the discussion
• Documentation: API Documentation

Changelog

See CHANGELOG.md for a detailed history of changes.

---

Made with ❤️ by Bhushan Rane