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 <PAT> 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://<your-host>/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 WWW-Authenticate: Bearer resource_metadata="…" header so Claude can discover the endpoints.

The prototype keeps OAuth token→PAT bindings in memory. For production, back them with a shared, encrypted store (e.g. Redis) so tokens survive restarts and work across replicas.

Behind a reverse proxy or load balancer, set NETBIRD_TRUST_PROXY (see Configuration) so the per-IP rate limits — the OAuth routes, the /oauth/netbird-login form, and per-source login PAT verification — key on the real client IP rather than the proxy's. Left unset behind a proxy, every client collapses into one bucket, which throttles everyone instead of isolating abusers.

Direct-PAT alternative (testing / simple deploys)

Instead of OAuth you can pass the NetBird PAT directly per request via the x-netbird-token header (configurable with NETBIRD_TOKEN_HEADER) or Authorization: Token <pat>. The token is used only for the life of the request and never persisted, so one deployment still serves many tenants. Authorization: Bearer is reserved for OAuth.

This path is off by default whenever OAuth is enabled — turn it on explicitly with NETBIRD_ENABLE_DIRECT_PAT=true (it is on automatically when OAuth is disabled, since it is then the only way to authenticate). When it is on, each request's base URL must be on the host allowlist — the configured NETBIRD_API_URL host plus anything in NETBIRD_ALLOWED_API_HOSTS — and the presented PAT is verified against NetBird before any tool runs, so the server can't be steered at an arbitrary host or driven with an unverified token.

Configuration

Boolean variables accept 1, true, yes, or on (case-insensitive) as true; any other value — including a typo — is treated as false, so a misspelled flag fails closed rather than silently enabling something.

Tools (v1)

Read tools are always on. Writes use a draft-and-confirm flow: call once to preview the exact request, then again with confirm: true to apply. Deletes are off by default — set NETBIRD_ENABLE_DESTRUCTIVE=true to enable them, and they require the exact resource id.

* destructive — gated behind NETBIRD_ENABLE_DESTRUCTIVE.

Out of scope for v1: Users/Accounts admin, Tokens, MSP, Invoice/Usage, and cloud-only IDP/EDR integration configs. DNS writes and posture-check authoring are v2. (OAuth is implemented — see "Connect it to your Claude account" above. Binding it to an upstream IdP login instead of a PAT is the remaining v2 auth step.)

Safety

• Client-side rate limiting under NetBird Cloud's 120 req/min, with exponential backoff honoring Retry-After on 429/5xx.
• Writes preview before applying; deletes are opt-in and require an exact id (never a batch).
• Tokens are never written to logs.