Netbird MCP Server Component

This project delivers a Model Context Protocol (MCP) interface layer for the Netbird peer-to-peer VPN solution. It functions as an MCP server.

This codebase builds upon the foundational work established by the MCP Server for Grafana from Grafana Labs, inheriting the permissive Apache License 2.0.

It incorporates the MCP Go library developed by Mark III Labs.

Status Advisory: This utility is currently under active development.

Acquisition Methods

From Source Compilation

Repository Cloning

bash git clone https://github.com/aantti/mcp-netbird

Building and Installation

bash cd mcp-netbird && \ make install

Via GitHub Direct Install

bash go install github.com/aantti/mcp-netbird/cmd/mcp-netbird@latest

Using Smithery

To automate the provisioning of the Netbird MCP Server for use with Claude Desktop via Smithery:

bash npx -y @smithery/cli install @aantti/mcp-netbird --client claude

Configuration Requirements

The server mandates the configuration of the following environment variables:

• NETBIRD_API_TOKEN: The necessary credential for authenticating against the Netbird management plane.
• NETBIRD_HOST (Optional): Specifies the alternative Netbird API endpoint (defaults to api.netbird.io).

Functional Capabilities

This component interrogates the Netbird API to surface configuration and operational data to Language Models. It currently features a direct mapping of select read-only Netbird API resources to available tools.

• [x] Data retrieval relies exclusively on the Netbird API interface.
• [x] Endpoint accessibility is customizable.
• [x] Secure access to the Netbird API is managed via token exchange.

Exposed Tools

Tool Identifier	Purpose	Corresponding Netbird API Reference
list_netbird_peers	Retrieves information for all connected network entities (peers).	List all Peers
list_netbird_port_allocations	Lists ingress port mappings associated with a specified peerId.	List all Port Allocations
list_netbird_groups	Fetches definitions for all defined user/machine groupings.	List all Groups
list_netbird_policies	Retrieves the network access control rule sets.	List all Policies
list_netbird_posture_checks	Retrieves configurations for security posture validation checks.	List all Posture Checks
list_netbird_networks	Lists the defined network segments accessible via the mesh.	List all Networks
list_netbird_nameservers	Retrieves details regarding configured DNS resolution groups.	List all Nameserver Groups

Integrating Novel Functionality

To augment the toolset:

1. Introduce a new source file within the tools/ directory (e.g., tools/users.go), utilizing existing code as a structural guide if necessary.
2. Define the necessary API routing and expected result structures within the new file.
3. Register the new capability within func newServer() located in cmd/main.go.

Operational Use

1. Obtain your requisite Netbird API authentication token from the management console interface.

2. Install the mcp-netbird executable binary using one of the installation paths documented above. Ensure the binary is accessible via the system's PATH environment variable.

3. Incorporate the server setup configuration into your host client's configuration file. For Codeium Windsurf, this configuration segment should be appended to ~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "netbird": { "command": "mcp-netbird", "args": [], "env": { "NETBIRD_API_TOKEN": "" } } } }

Refer to this resource for instructions on configuring Claude Desktop similarly.

Troubleshooting Tip: If Claude Desktop logs show an error similar to [netbird] [error] spawn mcp-netbird ENOENT, this indicates that the operating system cannot locate the executable; you must supply the absolute file path to mcp-netbird in the configuration. On macOS, these logs reside in ~/Library/Logs/Claude.

1. Test the integration by prompting queries such as, "Provide a summary of my Netbird peer connectivity, group assignments, and access protocols."

Containerization (Docker)

Build a container image and apply a tag:

bash docker build -t mcp-netbird-sse:v1 -f Dockerfile.sse .

Execute the container:

bash docker run --name mcp-netbird -p 8001:8001 -e NETBIRD_API_TOKEN= mcp-netbird-sse:v1

ToolHive Integration

ToolHive (thv) serves as a lightweight orchestration utility for deploying and managing MCP server instances.

Deployment and operation of the Netbird MCP via ToolHive is accomplished as follows:

1. Install thv following the instructions in the ToolHive primary README.

2. Securely register the Netbird API credential within thv's secret store:

bash thv secret set netbird

1. Generate the SSE-capable container image as detailed in the Docker section previously.

2. Initiate the Netbird MCP instance using thv run on port 8080:

bash thv run --secret netbird,target=NETBIRD_API_TOKEN --transport sse --name thv-mcp-netbird --port 8080 --target-port 8001 mcp-netbird-sse:v1

1. To gracefully terminate the server process:

bash thv stop thv-mcp-netbird

Development Workflow

We welcome community contributions! Please report any discovered issues or propose enhancements via an issue ticket or a pull request.

This application is implemented in the Go programming language. Ensure Go is installed according to your platform's standard setup procedures.

To initiate a local server instance:

bash export NETBIRD_API_TOKEN=your-token && \ go run cmd/mcp-netbird/main.go

Alternatively, for operation in Server-Sent Events (SSE) mode:

bash export NETBIRD_API_TOKEN=your-token && \ go run cmd/mcp-netbird/main.go --transport sse --sse-address :8001

Diagnostics

The MCP Inspector is available as an interactive environment designed for validating and troubleshooting MCP server interactions. Further details are available here.

To launch the MCP Inspector tool:

bash export NETBIRD_API_TOKEN=your-token && \ npx @modelcontextprotocol/inspector

Once launched, the Netbird MCP Server can be tested using either stdio or SSE transport protocols. If using stdio, the client UI must be directed to the full binary path of mcp-netbird.

Validation

Placeholder: Additional test cases are scheduled for implementation.

Code Quality Checks

To execute code linting routines:

bash make lint

Legal Disclaimer

This software is provided under the terms of the Apache License, Version 2.0.

This distribution incorporates components developed at Grafana Labs (https://grafana.com/).

This distribution incorporates components developed at Mark III Labs (https://github.com/mark3labs/mcp-go).

---

Note: The following appended context regarding cloud computing characteristics and history is retained from the original entry for contextual completeness but is extraneous to the Netbird MCP tool itself.

WIKIPEDIA: Cloud computing is "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand," according to ISO. It is commonly referred to as "the cloud".

== Characteristics == In 2011, the National Institute of Standards and Technology (NIST) identified five "essential characteristics" for cloud systems. Below are the exact definitions according to NIST:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service. By 2023, the International Organization for Standardization (ISO) had expanded and refined the list.

== History ==

The history of cloud computing extends to the 1960s, with the initial concepts of time-sharing becoming popularized via remote job entry (RJE). The "data center" model, where users submitted jobs to operators to run on mainframes, was predominantly used during this era. This was a time of exploration and experimentation with ways to make large-scale computing power available to more users through time-sharing, optimizing the infrastructure, platform, and applications, and increasing efficiency for end users. The "cloud" metaphor for virtualized services dates to 1994, when it was used by General Magic for the universe of "places" that mobile agents in the Telescript environment could "go". The metaphor is credited to David Hoffman, a General Magic communications specialist, based on its long-standing use in networking and telecom. The expression cloud computing became more widely known in 1996 when Compaq Computer Corporation drew up a business plan for future computing and the Internet. The company's ambition was to superch