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 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

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	Category	Description	Netbird API
`list_netbird_peers`	Peers	All peers	List all Peers
`list_netbird_port_allocations`	Ingress Ports	All ingress ports for `peerId`	List all Port Allocations
`list_netbird_groups`	Groups	All groups	List all Groups
`list_netbird_policies`	Policies	All policies	List all Policies
`list_netbird_posture_checks`	Posture Checks	All posture checks	List all Posture Checks
`list_netbird_networks`	Networks	All networks	List all Networks

Adding tools

To add new tools:

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

Usage

Get your Netbird API token from the Netbird management console.
Install the mcp-netbird binary using one of the installation methods above. Make sure the binary is in your PATH.

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.

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

claude-desktop-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 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).