Netbird MCP Server: Peers, Groups & Policies

Overview

The Netbird MCP Server is a lightweight control-plane component for managing Netbird (WireGuard-based) mesh networks. It centralizes information about peers, groups, and access policies so administrators and automation tools can inspect the topology, reason about connectivity, and enforce network-level access controls across a fleet of devices.

By exposing a simple API and configuration model, the MCP server makes it easier to list peers, group devices logically, and apply allow/deny policies. This is useful for network auditing, automated policy rollout, segmentation, and integrations with orchestration systems (CI/CD, service mesh controllers, or identity providers).

Features

• Lightweight control-plane service for Netbird-managed meshes
• Manage and list peers with metadata (IDs, keys, endpoints, tags)
• Define groups to organize peers (by team, role, or environment)
• Create policies that allow or restrict traffic between peers/groups and ports
• REST/gRPC API for querying and automation
• Config-driven operation suitable for Docker, systemd, or Kubernetes
• Useful for policy enforcement, network visibility, and automated workflows

Installation / Configuration

Below are sample ways to run the MCP server. Replace placeholders with values appropriate for your environment.

1. Run from a prebuilt binary (example)

# download and run (example binary name: mcp-netbird)
wget https://github.com/aantti/mcp-netbird/releases/download/vX.Y.Z/mcp-netbird_linux_amd64.tar.gz
tar xzf mcp-netbird_linux_amd64.tar.gz
./mcp-netbird --config /etc/mcp-netbird/config.yaml

2. Run with Docker

docker run --rm \
  -p 8080:8080 \
  -v /etc/mcp-netbird/config.yaml:/etc/mcp-netbird/config.yaml:ro \
  ghcr.io/aantti/mcp-netbird:latest \
  --config /etc/mcp-netbird/config.yaml

3. Example config (YAML)

server:
  bind: 0.0.0.0:8080
  tls: false

storage:
  type: file
  path: /var/lib/mcp-netbird/state.db

auth:
  token: "s3cr3t-token"  # token used for API calls (replace with vault/secret)

4. Example systemd unit

[Unit]
Description=Netbird MCP Server
After=network.target

[Service]
ExecStart=/usr/local/bin/mcp-netbird --config /etc/mcp-netbird/config.yaml
Restart=on-failure

[Install]
WantedBy=multi-user.target

API: Common endpoints

A typical MCP server exposes endpoints to list and mutate peers, groups, and policies. Example endpoints:

Example: list peers with curl

curl -H "Authorization: Bearer s3cr3t-token" \
  http://localhost:8080/api/v1/peers

Data model (summary)

• Peer: unique ID, WireGuard public key, endpoint (ip:port), tags/labels, group memberships.
• Group: logical collection of peers (name, description, selectors).
• Policy: allow/deny rules that reference peers/groups with match criteria (source, destination, ports, protocol, action).

Example policy (JSON)

{
  "id": "policy-allow-db",
  "name": "Allow app->db",
  "source": { "group": "apps" },
  "destination": { "group": "databases", "ports": ["5432"], "protocol": "tcp" },
  "action": "allow"
}

Available Resources

• GitHub repository: https://github.com/aantti/mcp-netbird — source code, releases, and examples
• API docs: check the repo for OpenAPI/Swagger spec (if provided) or README examples
• Example configs: look in the repo’s examples/ directory for ready-to-use YAML/JSON
• Integration ideas: use CI pipelines to push updated peer lists, or connect the MCP server to identity providers to automate group membership

Use Cases

1. Inventory and visibility

   • List all peers, their last-seen timestamps, tags and endpoints to audit current mesh membership and routing.

2. Network segmentation

   • Define groups (e.g., “frontend”, “backend”, “db”) and apply policies to only allow necessary flows (frontend -> backend over specific ports), implementing least privilege.

3. Temporary access workflows

   • Create ephemeral group membership for contractors or troubleshooting windows, and automatically revert after a timeout.

4. Automation & CI/CD

   • Automate policy deployment as part of a release: when a new service is deployed, add it to a group and create policies that allow traffic from a defined set of peers.

5. Integration with orchestration tools

   • Sync cluster/service labels into MCP groups, enabling dynamic policy updates as services scale.

Tips for Developers

• Keep authoritative data in source control or a secrets manager, and use automation to push changes into the MCP server.
• Use tokens or mutual TLS for authentication between clients and the server.
• Validate policies in a staging environment before applying to production to avoid accidental lockouts.
• If running in Kubernetes, consider exposing the server via a ClusterIP/Ingress and using RBAC for control-plane access.

For full implementation details, examples, and source code, consult the GitHub repository linked above.