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
Build and install
Installing from GitHub
Installing via Smithery
To install Netbird MCP Server for Claude Desktop automatically via Smithery:
Configuration
The server requires the following environment variables:
NETBIRD_API_TOKEN: Your Netbird API token
NETBIRD_HOST(optional): The Netbird API host (default isapi.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
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
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()incmd/main.go
Usage
- Get your Netbird API token from the Netbird management console.
- Install the
mcp-netbirdbinary 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:
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 ENOENTin Claude Desktop logs, you need to specify the full path tomcp-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
Docker
Build an image and tag it:
Run the image:
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:
- Install
thvas described in ToolHive README.
- Add Netbird API token to
thvsecrets:
- Build an SSE image as described in the Docker section above
- Start Netbird MCP with
thv runon port 8080:
- When you want to stop the server, use:
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:
Or in SSE mode:
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:
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:
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).
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
Build and install
Installing from GitHub
Installing via Smithery
To install Netbird MCP Server for Claude Desktop automatically via Smithery:
Configuration
The server requires the following environment variables:
NETBIRD_API_TOKEN: Your Netbird API token
NETBIRD_HOST(optional): The Netbird API host (default isapi.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
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
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()incmd/main.go
Usage
- Get your Netbird API token from the Netbird management console.
- Install the
mcp-netbirdbinary 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:
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 ENOENTin Claude Desktop logs, you need to specify the full path tomcp-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
Docker
Build an image and tag it:
Run the image:
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:
- Install
thvas described in ToolHive README.
- Add Netbird API token to
thvsecrets:
- Build an SSE image as described in the Docker section above
- Start Netbird MCP with
thv runon port 8080:
- When you want to stop the server, use:
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:
Or in SSE mode:
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:
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:
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).