内容
# NetBird MCP 服务器
一个适用于 [NetBird](https://netbird.io) 的 [MCP](https://modelcontextprotocol.io) 服务器，允许您通过 Claude 以自然语言管理您的网络 — 对等体、设置密钥、组、策略、网络和 DNS — 而不是通过仪表盘或原始的 REST 调用。
**一个代码库，两种运行方式：**
- **本地（标准输入输出）** — 作为 Claude Desktop / Claude Code 的子进程运行。凭证来自环境变量。
- **云（可流式 HTTP）** — 在云中托管，并作为远程/自定义连接器添加到 Claude。
无状态且多租户；每个请求都携带自己的 NetBird token。
入口点以下的所有内容（工具、API 客户端）都是共享的，因此两种模式都暴露相同的工具集。有关完整的设计和路线图，请参见 [`PLAN.md`](PLAN.md)。
---
## 安装与构建
```bash
npm install
npm run build
npm test # 单元测试（模拟 NetBird API）
```
## 获取 NetBird token
在 NetBird 仪表盘中创建一个 **服务用户**，并为其颁发一个 **个人访问令牌（PAT）**（NetBird 推荐用于组织范围的 API 流）。服务器在每次调用时都会将其作为 `Authorization: Token <PAT>` 发送。
---
## 在本地运行（标准输入输出）
**Claude Desktop** — 添加到 `claude_desktop_config.json`：
```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：**
```bash
claude mcp add netbird -e NETBIRD_API_TOKEN=nb_pat_xxx -- npx -y @netbird/mcp
```
**本地开发/调试** 使用 MCP 检验器：
```bash
cp .env.example .env # 填写 NETBIRD_API_TOKEN
npm run inspect
```
---
## 在云中运行（可流式 HTTP）
```bash
docker build -t netbird-mcp .
docker run -p 3000:3000 netbird-mcp
```
设置 `PUBLIC_BASE_URL` 为外部可达的 HTTPS 源（用于 OAuth 元数据）：
```bash
docker run -p 3000:3000 -e PUBLIC_BASE_URL=https://netbird-mcp.example.com netbird-mcp
```
服务器暴露：
- `POST /mcp` — MCP 端点（无状态）
- `GET /healthz` — 健康检查
- OAuth 2.1 端点（见下文）：`/.well-known/oauth-authorization-server`、
`/.well-known/oauth-protected-resource/mcp`、`/authorize`、`/token`、`/register`、`/revoke`
### 将其连接到您的 Claude 帐户（OAuth）
在 Claude 中将其添加为 **远程/自定义连接器**，指向 `https://<your-host>/mcp`。
然后，Claude 运行标准的 OAuth 2.1 流 — 它动态注册自己，您将被发送到一个 **"连接 NetBird"** 登录页面，您可以在其中粘贴您的 NetBird PAT。Claude 在服务器端接收一个绑定到该 PAT 的 OAuth 访问令牌；PAT 本身永远不会发送到 Claude。这是推荐的路径。
实现的流：OAuth 2.0 受保护资源 + 授权服务器元数据发现（RFC 9728 / 8414），动态客户端注册（RFC 7591），授权码授予与 **PKCE（S256）**，以及刷新令牌。未经身份验证的 `POST /mcp` 返回 `401`，带有 `WWW-Authenticate: Bearer resource_metadata="…"` 头部，因此 Claude 可以发现端点。
> 原型将 OAuth token→PAT 绑定 **存储在内存中**。对于生产环境，请使用共享的加密存储（例如 Redis）支持它们，以便令牌在重启后存活并在副本之间工作。
### 直接 PAT 替代方案（测试/简单部署）
您可以通过 `x-netbird-token` 头部（可使用 `NETBIRD_TOKEN_HEADER` 配置）或 `Authorization: Token <pat>` 直接传递 NetBird PAT，而不是使用 OAuth。对于直接 PAT 模式，每个请求使用 PAT 仅限于请求生命周期内，且从不持久化，因此一个部署仍可服务多个租户。`Authorization: Bearer` 保留用于 OAuth。禁用 OAuth 需设置 `NETBIRD_ENABLE_OAUTH=false`。
---
## 配置
| 变量 | 模式 | 默认值 | 目的 |
|----------|------|---------|---------|
| `NETBIRD_API_TOKEN` | 本地 | — | NetBird PAT（stdio 必需） |
| `NETBIRD_API_URL` | 两种模式 | `https://api.netbird.io` | API 基本 URL；为自托管设置 |
| `NETBIRD_ENABLE_DESTRUCTIVE` | 两种模式 | `false` | 启用 `delete_*` 工具 |
| `NETBIRD_MAX_RPM` | 两种模式 | `110` | 客户端速率限制（低于 NetBird 的 120/分钟） |
| `NETBIRD_TIMEOUT_MS` | 两种模式 | `30000` | 请求超时时间 |
| `LOG_LEVEL` | 两种模式 | `info` | `debug` \| `info` \| `warn` \| `error` |
| `PORT` | 云 | `3000` | HTTP 监听端口 |
| `PUBLIC_BASE_URL` | 云 | `http://localhost:PORT` | OAuth 元数据中公布的公共 HTTPS 源 |
| `NETBIRD_ENABLE_OAUTH` | 云 | `true` | 启用 OAuth 2.1 授权服务器 |
| `NETBIRD_VERIFY_PAT_ON_LOGIN` | 云 | `true` | OAuth 登录期间实时检查 PAT |
| `NETBIRD_TOKEN_HEADER` | 云 | `x-netbird-token` | 携带调用者 PAT 的头部（直接 PAT 模式） |
| `NETBIRD_URL_HEADER` | 云 | `x-netbird-api-url` | 可选的租户基本 URL 头部 |
布尔变量接受 `1`、`true`、`yes` 或 `on`（不区分大小写）作为真；任何其他值 — 包括拼写错误 — 都被视为 **假**，因此拼写错误的标志会失败并关闭，而不是静默启用某些功能。
---
## 工具（v1）
读取工具始终可用。写入使用 **草稿和确认** 流：先调用一次以预览确切的请求，然后再次调用并设置 `confirm: true` 以应用。删除 **默认关闭** — 设置 `NETBIRD_ENABLE_DESTRUCTIVE=true` 以启用它们，并且需要确切的资源 ID。
| 组 | 工具 |
|-------|-------|
| 对等体 | `list_peers`、`get_peer`、`list_accessible_peers`、`update_peer`、`delete_peer`\* |
| 设置密钥 | `list_setup_keys`、`create_setup_key`、`update_setup_key` |
| 组 | `list_groups`、`create_group`、`update_group`、`delete_group`\* |
| 策略 | `list_policies`、`get_policy`、`create_policy`、`update_policy`、`delete_policy`\* |
| 网络 | `list_networks`、`get_network` |
| DNS | `list_nameserver_groups`、`get_dns_settings` |
| 可见性 | `list_posture_checks`、`list_events` |
\* 破坏性 — 需要 `NETBIRD_ENABLE_DESTRUCTIVE` 支持。
**v1 范围外：** 用户/帐户管理、令牌、MSP、发票/用量和仅限云的 IDP/EDR 集成配置。DNS 写入和姿态检查编著属于 v2。（OAuth 已实现 — 请参见上面的“将其连接到您的 Claude 帐户”部分。与上游 IdP 登录绑定而不是 PAT 是剩余的 v2 身份验证步骤。）
---
## 安全
- 客户端速率限制低于 NetBird Cloud 的 120 req/min，具有指数级回退，遵守 `Retry-After` 以应对 429/5xx。
- 写入预览在应用之前；删除是按需开启的，需要精确的 ID（从不批量）。
- 令牌永远不会写入日志。
