使用说明

NetBird MCP服务器

全面模型上下文协议（MCP）服务器 NetBird 通过AI助手提供50多种工具，用于完整的VPN基础设施管理。

由XNet股份有限公司维护。
首席开发人员：Joshua S.Doucette

关于

此MCP服务器使Kiro、Claude Desktop和其他MCP客户端等AI助手能够以编程方式管理NetBird VPN基础设施。它提供：

50+管理工具：完成所有NetBird资源的CRUD操作
多个部署选项：本地STDIO、远程SSE或Docker MCP网关
高级策略管理：验证、依赖性跟踪和批量操作
辅助函数：组整合、策略模板和通用工作流
生产就绪：全面的错误处理、日志记录和安全功能

该项目最初源自Grafana Labs的Grafana MCP服务器，现已针对NetBird基础设施管理进行了大幅扩展和增强。

快速开始

Docker（推荐）

最简单的入门方法是将Docker与Docker MCP网关一起使用：

# Pull the latest image
docker pull xnetadmin/mcp-netbird:latest

# Run in SSE mode for remote access
docker run -d \
  --name mcp-netbird \
  -p 8001:8001 \
  -e NETBIRD_API_TOKEN=your_token_here \
  -e NETBIRD_API_HOST=api.netbird.io \
  xnetadmin/mcp-netbird:latest \
  -t sse -sse-address 0.0.0.0:8001

然后配置MCP客户端（请参阅配置在......下面

从版本安装

从以下位置下载适用于您平台的预构建二进制文件发布页面.

Linux（Debian/Ubuntu）:

wget https://github.com/XNet-NGO/mcp-netbird/releases/latest/download/mcp-netbird_VERSION_linux_x86_64.deb
sudo dpkg -i mcp-netbird_VERSION_linux_x86_64.deb

Linux（其他）:

wget https://github.com/XNet-NGO/mcp-netbird/releases/latest/download/mcp-netbird_VERSION_Linux_x86_64.tar.gz
tar -xzf mcp-netbird_VERSION_Linux_x86_64.tar.gz
sudo mv mcp-netbird /usr/local/bin/

macOS:

# Intel Macs
wget https://github.com/XNet-NGO/mcp-netbird/releases/latest/download/mcp-netbird_VERSION_Darwin_x86_64.tar.gz
tar -xzf mcp-netbird_VERSION_Darwin_x86_64.tar.gz
sudo mv mcp-netbird /usr/local/bin/

# Apple Silicon
wget https://github.com/XNet-NGO/mcp-netbird/releases/latest/download/mcp-netbird_VERSION_Darwin_arm64.tar.gz
tar -xzf mcp-netbird_VERSION_Darwin_arm64.tar.gz
sudo mv mcp-netbird /usr/local/bin/

视窗：从下载ZIP 发布，提取并添加到PATH。

从源头构建

git clone https://github.com/XNet-NGO/mcp-netbird
cd mcp-netbird
make install

或者直接从GitHub安装：

go install github.com/XNet-NGO/mcp-netbird/cmd/mcp-netbird@latest

配置

NetBird MCP服务器支持三种部署模式。选择最适合您用例的一个。

获取NetBird API代币

在配置之前，您需要一个NetBird API令牌：

登录您的NetBird仪表板(https://app.netbird.io或您的自托管实例）
首选 设置→ 访问令牌
创建一个 服务用户 （建议用于生产）或使用个人令牌
分配适当的角色： 管理员 （完全访问）或 网络管理员 （仅限网络管理）
生成并复制API令牌（从 nbp_)

部署选项

选项1:Docker MCP网关（推荐）

Docker MCP网关为远程MCP服务器提供最佳体验，处理本地STDIO和远程SSE之间的协议转换。

1.启用NetBird MCP服务器

创建或更新 ~/.docker/mcp/config.yaml:

netbird-mcp-server:
  netbird_host: api.netbird.io  # or your self-hosted domain
  enabled: true

2.设置您的API代币

创建或更新 ~/.docker/mcp/.env:

NETBIRD_API_TOKEN=nbp_your_token_here

3.配置您的MCP客户端

对于基罗 (~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": [
        "mcp",
        "gateway",
        "run",
        "--servers=netbird-mcp-server"
      ],
      "disabled": false,
      "autoApprove": ["*"]
    }
  }
}

对于 克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": [
        "mcp",
        "gateway",
        "run",
        "--servers=netbird-mcp-server"
      ]
    }
  }
}

4.验证设置

# Check server is enabled
docker mcp server list | grep netbird

# Restart your MCP client (Kiro/Claude Desktop)
# Tools will appear with mcp_MCP_DOCKER_ prefix

选项2：本地STDIO模式

在本地运行MCP服务器以进行开发或单用户场景。

献给基洛 (~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "netbird": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "xnetadmin/mcp-netbird:latest",
        "-t",
        "stdio"
      ],
      "env": {
        "NETBIRD_API_TOKEN": "nbp_your_token_here",
        "NETBIRD_API_HOST": "api.netbird.io"
      },
      "disabled": false
    }
  }
}

适用于克劳德桌面:

{
  "mcpServers": {
    "netbird": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "xnetadmin/mcp-netbird:latest",
        "-t",
        "stdio"
      ],
      "env": {
        "NETBIRD_API_TOKEN": "nbp_your_token_here",
        "NETBIRD_API_HOST": "api.netbird.io"
      }
    }
  }
}

选项3：远程SSE服务器

将MCP服务器部署为远程服务，供团队协作或生产使用。

1.部署MCP服务器

创建 docker-compose.yml:

version: '3.8'

services:
  mcp-netbird:
    image: xnetadmin/mcp-netbird:latest
    container_name: mcp-netbird-server
    restart: unless-stopped
    command: ["-t", "sse", "-sse-address", "0.0.0.0:8001"]
    environment:
      - NETBIRD_API_TOKEN=nbp_your_token_here
      - NETBIRD_API_HOST=api.netbird.io
    ports:
      - "8001:8001"

部署：

docker compose up -d

2.配置反向代理（可选但推荐）

卡迪 (Caddyfile):

mcp.example.com {
    reverse_proxy /sse localhost:8001 {
        flush_interval -1  # Required for SSE
    }
    redir / /sse
}

Nginx:

server {
    listen 443 ssl http2;
    server_name mcp.example.com;
    
    location /sse {
        proxy_pass http://localhost:8001;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;  # Required for SSE
        proxy_cache off;
        chunked_transfer_encoding off;
    }
}

3.配置Docker MCP网关

更新 ~/.docker/mcp/config.yaml:

netbird-mcp-server:
  url: https://mcp.example.com/sse
  transport: sse
  enabled: true

然后添加到MCP客户端配置中，如选项1所示。

配置优先

当多个配置源提供相同的值时：

CLI参数>HTTP标头>环境变量

例子：

# Environment variable
export NETBIRD_API_TOKEN="token-from-env"

# CLI argument overrides environment
mcp-netbird --api-token "token-from-cli"
# Result: Uses "token-from-cli"

自托管NetBird

对于自托管NetBird实例，请将API主机设置为您的域：

# Docker MCP Gateway
netbird-mcp-server:
  netbird_host: api.yourdomain.com
  enabled: true

或者对于STDIO模式：

{
  "env": {
    "NETBIRD_API_TOKEN": "your_token",
    "NETBIRD_API_HOST": "api.yourdomain.com"
  }
}

故障排除

工具未出现：配置更改后重新启动MCP客户端。

连接超时：验证API令牌是否有效以及是否具有适当的权限。

401未经授权：请检查您的API令牌是否尚未过期。

有关详细的设置说明，请参阅 docs/MCP_SETUP_GUIDE.md.

特性

完整的NetBird API覆盖范围

MCP服务器提供50多种工具，涵盖所有NetBird资源：

资源	操作	描述
同行	列表、获取、更新、删除	管理网络对等体及其配置
群组	列表、获取、创建、更新、删除	将对等体组织到逻辑组中
政策	列表、获取、创建、更新、删除	控制组之间的网络访问
网络	列表、获取、创建、更新、删除	管理网络配置
网络资源	列表、获取、创建、更新、删除	定义网络子网和资源
网络路由器	列表、获取、创建、更新、删除	为网络配置路由对等体
域名服务器	列表、获取、创建、更新、删除	管理DNS名称服务器组
路线	列表、获取、创建、更新、删除	配置网络路由（旧版）
设置键	列表、获取、创建、更新、删除	生成对等注册密钥
用户	列表、获取、邀请、更新、删除	管理用户帐户和权限
姿势检查	列表、获取、创建、更新、删除	定义安全态势要求
端口分配	列表、获取、创建、更新、删除	管理入口端口转发
账户	获取、更新	配置全帐户设置

辅助工具

用于常见管理工作流的高级工具：

列表_政策_组：查找引用特定组的所有策略
replace_group_in_policies：批量替换所有策略中的组
get_policy_template：获取带有文档的示例策略结构

关键能力

✅ 完整的CRUD操作：创建、读取、更新和删除所有NetBird资源
✅ 策略验证：在提交API之前自动验证策略规则
✅ 依赖项跟踪：查找和管理资源依赖关系
✅ 批量操作：跨多个资源执行操作
✅ 错误处理：全面的错误消息和恢复建议
✅ 生产就绪：安全的身份验证、日志记录和监控支持

用法示例

基本操作

列出所有同行:

mcp_MCP_DOCKER_list_netbird_peers()
// Returns: Array of peer objects with IP, status, groups, etc.

创建组:

mcp_MCP_DOCKER_create_netbird_group({
  name: "developers",
  peers: []  // Add peer IDs here
})

创建设置密钥:

mcp_MCP_DOCKER_create_netbird_setup_key({
  name: "dev-team-key",
  type: "reusable",
  expires_in: 2592000,  // 30 days
  auto_groups: ["dev-group-id"],
  usage_limit: 50
})

策略管理

创建一个简单的策略:

mcp_MCP_DOCKER_create_netbird_policy({
  name: "Admin SSH Access",
  description: "Allow admins to SSH to servers",
  enabled: true,
  rules: [{
    name: "SSH Rule",
    enabled: true,
    action: "accept",
    bidirectional: false,
    protocol: "tcp",
    sources: ["admin-group-id"],
    destinations: ["server-group-id"],
    port_ranges: [{ start: 22, end: 22 }]
  }]
})

使用组查找策略:

mcp_MCP_DOCKER_list_policies_by_group({
  group_id: "d535b93ngf8s73892nng"
})
// Returns: List of policies referencing this group

在所有策略中替换组:

mcp_MCP_DOCKER_replace_group_in_policies({
  old_group_id: "old-group-id",
  new_group_id: "new-group-id"
})
// Updates all policies to use the new group

网络配置

创建网络:

const network = mcp_MCP_DOCKER_create_netbird_network({
  name: "production-network",
  description: "Production infrastructure"
})

添加网络资源:

mcp_MCP_DOCKER_create_netbird_network_resource({
  network_id: network.id,
  name: "database-subnet",
  address: "10.0.1.0/24",
  enabled: true,
  groups: ["db-group-id"]
})

配置网络路由器:

mcp_MCP_DOCKER_create_netbird_network_router({
  network_id: network.id,
  peer: "router-peer-id",
  metric: 100,
  masquerade: true,
  enabled: true
})

DNS配置

添加名称服务器组:

mcp_MCP_DOCKER_create_netbird_nameserver({
  name: "Cloudflare DNS",
  description: "Primary DNS resolver",
  nameservers: [
    { ip: "1.1.1.1", ns_type: "udp", port: 53 },
    { ip: "1.0.0.1", ns_type: "udp", port: 53 }
  ],
  enabled: true,
  groups: ["all-group-id"],
  primary: true,
  domains: [],
  search_domains_enabled: false
})

完整工作流示例

以下是设置新环境的完整示例：

// 1. Create groups
const adminGroup = mcp_MCP_DOCKER_create_netbird_group({
  name: "admins",
  peers: []
})

const serverGroup = mcp_MCP_DOCKER_create_netbird_group({
  name: "servers",
  peers: []
})

// 2. Create setup keys
const adminKey = mcp_MCP_DOCKER_create_netbird_setup_key({
  name: "admin-key",
  type: "reusable",
  expires_in: 2592000,
  auto_groups: [adminGroup.id],
  usage_limit: 10
})

const serverKey = mcp_MCP_DOCKER_create_netbird_setup_key({
  name: "server-key",
  type: "reusable",
  expires_in: 2592000,
  auto_groups: [serverGroup.id],
  usage_limit: 100
})

// 3. Create policy
mcp_MCP_DOCKER_create_netbird_policy({
  name: "Admin Access",
  description: "Allow admins to access servers",
  enabled: true,
  rules: [{
    name: "Admin to Servers",
    enabled: true,
    action: "accept",
    bidirectional: true,
    protocol: "all",
    sources: [adminGroup.id],
    destinations: [serverGroup.id]
  }]
})

// 4. Configure DNS
mcp_MCP_DOCKER_create_netbird_nameserver({
  name: "Primary DNS",
  nameservers: [
    { ip: "1.1.1.1", ns_type: "udp", port: 53 }
  ],
  enabled: true,
  groups: [adminGroup.id, serverGroup.id],
  primary: true
})

// Setup keys can now be used to enroll peers
console.log("Admin key:", adminKey.key)
console.log("Server key:", serverKey.key)

使用AI助手

配置后，您可以通过自然语言与NetBird交互：

Kiro/Claude桌面:

“你能解释一下我的NetBird对等体、组和策略吗？”
“创建一个名为“开发人员”的新组，并为其生成设置密钥”
“显示引用管理员组的所有策略”
“配置DNS以对所有对等端使用Cloudflare”

有关更多示例和详细文档，请参阅 docs/MCP_SETUP_GUIDE.md.

高级用法

策略规则格式

在创建或更新策略时，规则必须遵循以下结构：

{
  "name": "Rule Name",
  "description": "Optional description",
  "enabled": true,
  "action": "accept",
  "bidirectional": true,
  "protocol": "all",
  "sources": ["group-id-1"],
  "destinations": ["group-id-2"],
  "port_ranges": [
    {"start": 80, "end": 80},
    {"start": 443, "end": 443}
  ]
}

必填字段:

name, enabled, action, bidirectional, protocol
至少一个源（组ID数组或sourceResource对象）
至少一个目标（组ID数组或destinationResource对象）

可选字段:

description, port_ranges （仅TCP/UDP）， authorized_groups

获取策略模板:

mcp_MCP_DOCKER_get_policy_template()
// Returns example policy structures with documentation

群组管理

查找组依赖关系:

mcp_MCP_DOCKER_list_policies_by_group({
  group_id: "d535b93ngf8s73892nng"
})
// Returns all policies referencing this group

强制删除组 （从所有策略中删除）：

mcp_MCP_DOCKER_delete_netbird_group({
  group_id: "group-id",
  force: true
})

生产部署

对于生产环境，将MCP服务器部署为远程SSE服务：

使用Docker Compose进行部署 （参见配置)
配置反向代理 使用SSL/TLS（Caddy或Nginx）
设置监控 以及日志记录
使用服务用户 具有适当的权限
旋转API令牌 定期

看 docs/MCP_SETUP_GUIDE.md 获取详细的生产部署指南。

码头工人

构建自定义图像

构建并标记图像：

docker build -t mcp-netbird-sse:v1 -f Dockerfile.sse .

使用不同的配置方法运行：

环境变量:

docker run --name mcp-netbird -p 8001:8001 \
  -e NETBIRD_API_TOKEN=your_token \
  -e NETBIRD_API_HOST=api.netbird.io \
  mcp-netbird-sse:v1

命令行参数:

docker run --name mcp-netbird -p 8001:8001 \
  mcp-netbird-sse:v1 \
  --transport sse \
  --sse-address :8001 \
  --api-token your_token \
  --api-host api.netbird.io

无状态（HTTP标头）:

# Run without credentials
docker run --name mcp-netbird -p 8001:8001 mcp-netbird-sse:v1

# Pass credentials per request
curl -X POST http://localhost:8001/sse \
  -H "X-Netbird-API-Token: your_token" \
  -H "X-Netbird-Host: api.netbird.io" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

使用ToolHive

ToolHive 简化了MCP服务器部署：

# Install thv
# See: https://github.com/StacklokLabs/toolhive#installation

# Add NetBird API token
thv secret set netbird

# Build SSE image
docker build -t mcp-netbird-sse:v1 -f Dockerfile.sse .

# Start server
thv run --secret netbird,target=NETBIRD_API_TOKEN \
  --transport sse \
  --name thv-mcp-netbird \
  --port 8080 \
  --target-port 8001 \
  mcp-netbird-sse:v1

# Stop server
thv stop thv-mcp-netbird

发展

欢迎投稿！请打开问题或提交拉取请求。

先决条件

转到1.21或更高版本
Docker（用于测试SSE模式）
Make（可选，方便命令）

本地运行

STDIO模式:

export NETBIRD_API_TOKEN=your_token
go run cmd/mcp-netbird/main.go

SSE模式:

go run cmd/mcp-netbird/main.go \
  --transport sse \
  --sse-address :8001 \
  --api-token your_token \
  --api-host api.netbird.io

使用MCP检查器进行调试

这 MCP 检查员是用于测试MCP服务器的交互式工具：

# Install and run
npx @modelcontextprotocol/inspector

# In the UI, configure:
# - Transport: stdio or sse
# - Command: mcp-netbird --api-token your_token
# - Or URL: http://localhost:8001/sse (for SSE mode)

测试

运行测试套件：

make test

运行特定测试：

go test ./tools -v -run TestListPeers

代码检查

make lint

添加新工具

在中创建新文件 tools/ （例如。， tools/new_resource.go)
按照现有模式实现工具功能
将工具添加到 func newServer() 在 cmd/mcp-netbird/main.go
在中添加测试 tools/new_resource_test.go
更新文档

项目结构

mcp-netbird/
├── cmd/mcp-netbird/     # Main application entry point
├── tools/               # MCP tool implementations
│   ├── peers.go
│   ├── groups.go
│   ├── policies.go
│   └── ...
├── docs/                # Documentation
│   └── MCP_SETUP_GUIDE.md
├── Dockerfile           # STDIO mode container
├── Dockerfile.sse       # SSE mode container
└── Makefile            # Build and development commands

文档

MCP设置指南：包含所有部署选项的全面设置指南
NetBird API文档：NetBird API官方参考
模型上下文协议：MCP规范和文件

支持和社区

问题: GitHub问题
讨论: GitHub讨论
NetBird社区: NetBird Slack

许可证

该项目根据 Apache许可证，版本2.0.

归因

该项目最初源于 Grafana的MCP服务器由Grafana Labs开发。当前的代码库已针对NetBird基础架构管理进行了大幅修改和扩展。

此项目使用 MCP Go 由Mark III实验室开发。

由XNet股份有限公司维护|首席开发人员：Joshua S.Doucette

如有疑问或支持，请在GitHub上发布问题或通过我们的社区渠道联系我们。