Netbird MCP Server: Centralized Security & Scalable Control

Key Features of Netbird MCP Server: Centralized Security & Scalable Control?

• Peer visibility: Retrieve connection status, geolocation, system metadata, and group memberships for all devices in your network.
• Custom API endpoints: Override default Netbird API host to work with private or self-hosted instances.
• Secure authentication: Uses token-based access controlled via environment variables to prevent unauthorized queries.
• Development flexibility: Supports both stdio and Server-Sent Events (SSE) transports for debugging workflows with tools like the MCP Inspector.

Use Cases of Netbird MCP Server: Centralized Security & Scalable Control?

Organizations can leverage this tool for:

• Network auditing: Generate compliance reports by programmatically fetching peer and policy configurations.
• Automated workflows: Integrate with chatbots or IAs to instantly check connectivity status or policy coverage across distributed devices.
• Incident response: Quickly identify disconnected peers or unauthorized group assignments during security investigations.
• Multi-platform support: Works seamlessly with both desktop apps (Claude Desktop) and command-line tools for varied deployment needs.

FAQ from Netbird MCP Server: Centralized Security & Scalable Control?

Why do I get an “ENOENT” error?

If the MCP client can’t find the executable, specify the full path to mcp-netbird in your configuration. On macOS, check logs at ~/Library/Logs/Claude for troubleshooting clues.

How do I test changes during development?

Use the MCP Inspector tool: npx @modelcontextprotocol/inspector and select the Netbird server for real-time debugging with either transport mode.

Is there community support?

Yes! Open issues or PRs on the GitHub repository for feature requests or bug reports. Contributions are encouraged!

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.

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

• List Netbird peers with detailed information
  • Connected status
  • Location information
  • System details
  • Group membership
• Configurable API endpoint
• Secure token-based authentication

Tools

Tool	Category	Description
list_netbird_peers	Peers	List all peers in your Netbird network
list_netbird_groups	Groups	List all groups in your Netbird network
list_netbird_policies	Policies	List all policies in your Netbird network

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": ""
   }
   }
   }

}

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

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.

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/).