Netbird

What is mcp-netbird?

mcp-netbird is an MCP (Model Context Protocol) server designed to integrate Netbird network data with Large Language Models (LLMs). It acts as a bridge, allowing LLMs to query and understand various aspects of a Netbird network, such as peers, groups, policies, and more, by leveraging the Netbird API.

How to use mcp-netbird?

Installation:

• From source: Clone the repository and run make install.
• From GitHub: Use go install github.com/aantti/mcp-netbird/cmd/mcp-netbird@latest.
• Via Smithery: Use npx -y @smithery/cli install @aantti/mcp-netbird --client claude for automatic installation with Claude Desktop.

Configuration: Set the NETBIRD_API_TOKEN environment variable with your Netbird API token. Optionally, set NETBIRD_HOST if your Netbird API host is not api.netbird.io.

Integration with LLM Clients (e.g., Claude Desktop):

1. Obtain your Netbird API token.
2. Install the mcp-netbird binary.
3. Configure your LLM client (e.g., ~/.codeium/windsurf/mcp_config.json for Codeium Windsurf) to include mcp-netbird as an MCP server, providing the command and environment variables (especially NETBIRD_API_TOKEN).
4. Ask questions to your LLM client like "Can you explain my Netbird peers, groups and policies to me?"

Docker: Build and run a Docker image using the provided Dockerfile.sse.

ToolHive: Deploy and manage mcp-netbird using ToolHive (thv) for simplified deployment and secret management.

Key Features of mcp-netbird

• Netbird API Integration: Accesses Netbird configuration and status via the official API.
• Configurable API Endpoint: Allows specifying a custom Netbird API host.
• Secure Authentication: Uses token-based authentication for the Netbird API.
• Comprehensive Toolset: Provides tools to list:
  • Netbird Peers
  • Netbird Port Allocations
  • Netbird Groups
  • Netbird Policies
  • Netbird Posture Checks
  • Netbird Networks
  • Netbird Nameservers
• Extensible: Easy to add new tools by creating new files in the tools directory and updating func newServer().

Use Cases of mcp-netbird

• Network Monitoring and Analysis: LLMs can be used to quickly retrieve and analyze the current state of a Netbird network, including connected peers, defined policies, and group memberships.
• Automated Network Auditing: Facilitates automated checks of Netbird configurations against best practices or compliance requirements.
• Intelligent Network Troubleshooting: LLMs can assist in diagnosing network issues by querying Netbird data and providing insights.
• Simplified Network Management: Provides a natural language interface for interacting with Netbird, making network management more accessible.

FAQ about mcp-netbird

Q: Is mcp-netbird still in development? A: Yes, the project is still under active development.

Q: What environment variables are required? A: NETBIRD_API_TOKEN is required. NETBIRD_HOST is optional.

Q: How can I debug mcp-netbird? A: You can use the MCP Inspector, an interactive developer tool, by running npx @modelcontextprotocol/inspector and configuring it to connect to your mcp-netbird instance.

Q: How can I contribute to mcp-netbird? A: Contributions are welcome! You can open an issue or submit a pull request. The project is written in Go.

Netbird MCP Server

A Model Context Protocol (MCP) server for Netbird.

This project is derived from the MCP Server for Grafana by Grafana Labs and is licensed under the same Apache License 2.0.

It also uses MCP Go by Mark III Labs.

Note: this project is still in development.

Installing

Installing from source

Clone the repository

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

Build and install

cd mcp-netbird && \
make install

Installing from GitHub

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

Installing via Smithery

To install Netbird MCP Server for Claude Desktop automatically via Smithery:

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

Configuration

The server requires the following environment variables:

• NETBIRD_API_TOKEN: Your Netbird API token
• NETBIRD_HOST (optional): The Netbird API host (default is api.netbird.io)

Features

This server uses the Netbird API to provide LLMs information about Netbird network. Currently it's a 1:1 mapping of select read-only Netbird API resources to tools.

• Uses Netbird API to access configuration and status
• Configurable API endpoint
• Secure token-based authentication for Netbird API

Tools

Tool	Description	Netbird API
list_netbird_peers	All peers	List all Peers
list_netbird_port_allocations	All ingress ports for peerId	List all Port Allocations
list_netbird_groups	All groups	List all Groups
list_netbird_policies	All policies	List all Policies
list_netbird_posture_checks	All posture checks	List all Posture Checks
list_netbird_networks	All networks	List all Networks
list_netbird_nameservers	All nameserver groups	List all Nameserver Groups

Adding tools

To add new tools:

1. Create a new file in tools (e.g., tools/users.go), possibly use existing code as a template
2. Add API route and response specifics to the new file
3. Add the tool to func newServer() in cmd/main.go

Usage

1. Get your Netbird API token from the Netbird management console.

2. Install the mcp-netbird binary using one of the installation methods above. Make sure the binary is in your PATH.

3. Add the server configuration to your client configuration file. E.g., for Codeium Windsurf add the following to ~/.codeium/windsurf/mcp_config.json:

   {
     "mcpServers": {
       "netbird": {
         "command": "mcp-netbird",
         "args": [],
         "env": {
           "NETBIRD_API_TOKEN": "<your-api-token>"
         }
       }
     }
   }
   

For more information on how to add a similar configuration to Claude Desktop, see here.

Note: if you see something along the lines of [netbird] [error] spawn mcp-netbird ENOENT in Claude Desktop logs, you need to specify the full path to mcp-netbird. On macOS Claude Logs are in ~/Library/Logs/Claude.

4. Try asking questions along the lines of "Can you explain my Netbird peers, groups and policies to me?"

Docker

Build an image and tag it:

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

Run the image:

docker run --name mcp-netbird -p 8001:8001 -e NETBIRD_API_TOKEN=<your-api-token> mcp-netbird-sse:v1

ToolHive

ToolHive (thv) is a lightweight utility designed to simplify the deployment and management of MCP servers.

You can use ToolHive to deploy and run Netbird MCP as follows:

1. Install thv as described in ToolHive README.

2. Add Netbird API token to thv secrets:

thv secret set netbird

3. Build an SSE image as described in the Docker section above

4. Start Netbird MCP with thv run on port 8080:

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

5. When you want to stop the server, use:

thv stop thv-mcp-netbird

Development

Contributions are welcome! Please open an issue or submit a pull request if you have any suggestions or improvements.

This project is written in Go. Install Go following the instructions for your platform.

To run the server manually, use:

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

Or in SSE mode:

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

Debugging

The MCP Inspector is an interactive developer tool for testing and debugging MCP servers. Read more about it here.

Here's how to start the MCP Inspector:

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

Netbird MCP Server can then be tested with either stdio or SSE transport type. For stdio specify the full path to mcp-netbird in the UI.

Testing

TODO: add more tests

Linting

To lint the code, run:

make lint

License

This project is licensed under the Apache License, Version 2.0.

This project includes software developed at Grafana Labs (https://grafana.com/).

This project includes software developed at Mark III Labs (https://github.com/mark3labs/mcp-go).