Netbird MCP Server

Netbird MCP 服务

一个适用于 Netbird 的 Model Context Protocol（MCP）服务。

本项目源自 Grafana Labs 的 MCP Server for Grafana，并采用相同的 Apache License 2.0 许可。

本项目还使用了 Mark III Labs 的 MCP Go。

注意：本项目仍在开发中。

安装

从源代码安装

克隆仓库

git clone https://github.com/aantti/mcp-netbird

构建并安装

cd mcp-netbird && \
make install

从 GitHub 安装

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

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Netbird MCP Server：

npx -y @smithery/cli install @aantti/mcp-netbird --client claude

配置

该服务需要以下环境变量：

• NETBIRD_API_TOKEN：你的 Netbird API 令牌
• NETBIRD_HOST（可选）：Netbird API 主机（默认为 api.netbird.io）

功能

该服务使用 Netbird API 为大模型提供 Netbird 网络信息。目前，它将部分只读 Netbird API 资源一对一映射为工具。

• 使用 Netbird API 访问配置和状态
• 可配置 API 端点
• 使用令牌进行安全的 Netbird API 身份验证

工具

工具	描述	Netbird API
list_netbird_peers	所有对等节点	列出所有对等节点
list_netbird_port_allocations	peerId 的所有入口端口	列出所有端口分配
list_netbird_groups	所有组	列出所有组
list_netbird_policies	所有策略	列出所有策略
list_netbird_posture_checks	所有状态检查	列出所有状态检查
list_netbird_networks	所有网络	列出所有网络
list_netbird_nameservers	所有名称服务器组	列出所有名称服务器组

添加工具

添加新工具：

1. 在 tools 中创建一个新文件（例如 tools/users.go），可以使用现有代码作为模板
2. 在新文件中添加 API 路由和响应详情
3. 在 cmd/main.go 中的 func newServer() 里添加该工具

使用

1. 从 Netbird 管理控制台获取你的 Netbird API 令牌。

2. 使用上述任一安装方式安装 mcp-netbird 二进制文件。确保该二进制文件位于 PATH 中。

3. 将服务配置添加到客户端配置文件中。例如，对于 Codeium Windsurf，将以下内容添加到 ~/.codeium/windsurf/mcp_config.json：

   {
     "mcpServers": {
       "netbird": {
         "command": "mcp-netbird",
         "args": [],
         "env": {
           "NETBIRD_API_TOKEN": "<your-api-token>"
         }
       }
     }
   }
   

有关如何在 Claude Desktop 中添加类似配置的更多信息，请参阅此处。

注意：如果你在 Claude Desktop 日志中看到类似 [netbird] [error] spawn mcp-netbird ENOENT 的内容，则需要指定 mcp-netbird 的完整路径。在 macOS 上，Claude 日志位于 ~/Library/Logs/Claude。

4. 尝试询问类似“你能为我解释一下 Netbird 对等节点、组和策略吗？”的问题。

Docker

构建镜像并为其添加标签：

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

运行镜像：

docker run --name mcp-netbird -p 8001:8001 -e NETBIRD_API_TOKEN=<your-api-token> mcp-netbird-sse:v1

ToolHive

ToolHive（thv）是一款轻量级实用工具，旨在简化 MCP 服务的部署和管理。

你可以使用 ToolHive 按照以下步骤部署并运行 Netbird MCP：

1. 按照 ToolHive README 中的说明安装 thv。

2. 将 Netbird API 令牌添加到 thv 密钥中：

thv secret set netbird

3. 按照 Docker 部分上文的说明构建 SSE 镜像。

4. 使用 thv run 在端口 8080 上启动 Netbird MCP：

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

5. 要停止服务时，请使用：

thv stop thv-mcp-netbird

开发

欢迎贡献！如果你有任何建议或改进意见，请提交 issue 或拉取请求。

本项目使用 Go 编写。请按照适用于你平台的说明安装 Go。

要手动运行服务，请使用：

export NETBIRD_API_TOKEN=your-token && \
go run cmd/mcp-netbird/main.go

或者以 SSE 模式运行：

export NETBIRD_API_TOKEN=your-token && \
go run cmd/mcp-netbird/main.go --transport sse --sse-address :8001

调试

MCP Inspector 是一款交互式开发工具，用于测试和调试 MCP 服务。点击此处了解更多信息。

启动 MCP Inspector 的方法如下：

export NETBIRD_API_TOKEN=your-token && \
npx @modelcontextprotocol/inspector

然后可以使用 stdio 或 SSE 传输类型测试 Netbird MCP Server。对于 stdio，请在 UI 中指定 mcp-netbird 的完整路径。

测试

TODO：添加更多测试

代码检查

要检查代码，请运行：

make lint

许可证

本项目采用 Apache License, Version 2.0 许可。

本项目包含由 Grafana Labs (https://grafana.com/) 开发的软件。

本项目包含由 Mark III Labs (https://github.com/mark3labs/mcp-go) 开发的软件。