NetBird MCP Server

An MCP server for NetBird that lets you manage your network — peers, setup keys, groups, policies, networks and DNS — from Claude in natural language, instead of the dashboard or raw REST calls.

One codebase, two ways to run:

• Local (stdio) — runs as a subprocess of Claude Desktop / Claude Code. Credentials from env.
• Cloud (Streamable HTTP) — hosted and added to Claude as a remote/custom connector. Stateless and multi-tenant; each request carries its own NetBird token.

Everything below the entrypoint (tools, API client) is shared, so both modes expose the identical tool set. See PLAN.md for the full design and roadmap.

---

Install & build

npm install
npm run build
npm test        # unit tests (mocked NetBird API)

Getting a NetBird token

Create a service user in the NetBird dashboard and issue a Personal Access Token (PAT) for it (NetBird’s recommendation for org-wide API flows). The server sends it as Authorization: Token on every call.

---

Run locally (stdio)

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "netbird": {
      "command": "npx",
      "args": ["-y", "@netbird/mcp"],
      "env": {
        "NETBIRD_API_TOKEN": "nb_pat_xxx",
        "NETBIRD_API_URL": "https://api.netbird.io"
      }
    }
  }
}

Claude Code:

claude mcp add netbird -e NETBIRD_API_TOKEN=nb_pat_xxx -- npx -y @netbird/mcp

Local dev / debugging with the MCP Inspector:

cp .env.example .env   # fill in NETBIRD_API_TOKEN
npm run inspect

---

Run in the cloud (Streamable HTTP)

docker build -t netbird-mcp .
docker run -p 3000:3000 netbird-mcp

Set PUBLIC_BASE_URL to the externally reachable HTTPS origin (used in the OAuth metadata):

docker run -p 3000:3000 -e PUBLIC_BASE_URL=https://netbird-mcp.example.com netbird-mcp

The server exposes:

• POST /mcp — the MCP endpoint (stateless)
• GET /healthz — health check
• OAuth 2.1 endpoints (see below): /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource/mcp, /authorize, /token, /register, /revoke

Connect it to your Claude account (OAuth)

Add it in Claude as a remote / custom connector pointing at https:///mcp. Claude then runs a standard OAuth 2.1 flow — it registers itself dynamically, and you’ll be sent to a “Connect NetBird” login page where you paste your NetBird PAT once. Claude receives an OAuth access token bound to that PAT server-side; the PAT itself never goes to Claude. This is the recommended path.

The flow implemented: OAuth 2.0 Protected Resource + Authorization Server metadata discovery (RFC 9728 / 8414), Dynamic Client Registration (RFC 7591), authorization-code grant with PKCE (S256), and refresh tokens. An unauthenticated POST /mcp returns 401 with a