home / mcp / netbird mcp server

Netbird MCP Server

MCP Server for Netbird

Installation

Add the following to your MCP client configuration file.

Configuration

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

Netbird MCP Server exposes Netbird network data to clients via the MCP (Model Context Protocol). It lets you query Netbird configuration and status through a structured set of tools, enabling you to build conversational and programmatic assistants around Netbird data. This server is written in Go and is designed to work with MCP clients to fetch read‑only Netbird resources securely.

How to use

You connect to the Netbird MCP Server as an MCP provider. Use an MCP client to load the server configuration and invoke the available tools to retrieve information about Netbird peers, port allocations, groups, policies, posture checks, networks, and nameservers. Each tool maps to a specific Netbird API resource and returns structured results that you can present to users or feed into other workflows.

How to install

# Prerequisites: Git, Go, and a shell environment
# 1) Install from source
git clone https://github.com/aantti/mcp-netbird
cd mcp-netbird
make install

# 2) Install from Go directly
go install github.com/aantti/mcp-netbird/cmd/mcp-netbird@latest

# 3) Smithery (for automated client-based deployments)
npx -y @smithery/cli install @aantti/mcp-netbird --client claude
```

Explanation:
- Building from source lets you install a local binary with the provided Makefile targets.
- Installing via Go gets the latest prebuilt binary into your Go bin directory.
- Smithery provides a way to provision MCP servers for client apps directly. You can use it to set up specific clients with the mcp-netbird tool included.
"}]} ,{

Configuration and usage notes

Configure your MCP client to load Netbird as a server. You will provide a runtime command and environment to run the MCP server alongside your client. The following example demonstrates how to register Netbird as an MCP server in your client configuration.

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

Security and environment

The Netbird MCP Server relies on a token-based approach to access the Netbird API. You must provide a valid NETBIRD_API_TOKEN. The token is used to authenticate with Netbird services and to authorize MCP tool access.

Running with Docker

You can run a container with the Netbird MCP Server image and provide your API token as an environment variable.

# Build and run example image
# (Note: replace <your-api-token> with a valid token)
docker run --name mcp-netbird -p 8001:8001 -e NETBIRD_API_TOKEN=<your-api-token> mcp-netbird-sse:v1
```
"}]} ,{

Tool integration and available endpoints

The MCP server exposes a set of read-only tools that bridge Netbird API resources to MCP. Each tool corresponds to a specific Netbird resource and can be invoked by your MCP client to fetch structured data.

Development and testing

If you are contributing, you can run the server locally to test MCP interactions. Set up the environment, then start the server in development mode. For debugging, you can use MC Inspector and connect with either stdio or SSE transports.

Available tools

list_netbird_peers

Retrieves all Netbird peers registered in your network.

list_netbird_port_allocations

Lists all port allocations for a given peer, showing ingress ports.

list_netbird_groups

Fetches all Netbird groups in your configuration.

list_netbird_policies

Returns all Netbird policies applied in your networks.

list_netbird_posture_checks

Retrieves posture checks configured for Netbird.

list_netbird_networks

Lists all Netbird networks in your account.

list_netbird_nameservers

Gets all Netbird nameserver groups.