内容
# NetBox MCP 服务器
一个使用 FastMCP 构建的小型模型上下文协议（MCP）服务器，提供与 NetBox 实例的接口。
该仓库将 NetBox 资源（站点、站点组、设备等）作为 MCP 工具公开，并运行流式 HTTP 传输，以便客户端可以连接并接收来自 MCP 服务器的流式响应。
## 架构（FastMCP + 流式 HTTP）
- FastMCP：MCP 工具注册表和运行时。工具在 `app.py` 中定义，并使用 `@mcp.tool` 进行装饰。
- NetBoxClient：`app.py` 中的一个小型异步助手，封装了 `httpx.AsyncClient` 以调用 NetBox API。
- 流式 HTTP 传输：MCP 服务器使用 `mcp.run(transport="http", ...)` 启动，这运行一个支持流式/分块响应传输的 HTTP 服务器。这对于希望增量消耗事件或长时间运行的响应而不是等待整个结果的客户端非常有用。
概念上的流程是：
1. 客户端连接到 FastMCP 流式 HTTP 端点。
2. 客户端请求一个工具（例如，`search_sites` 或 `get_site_group_details`）。
3. FastMCP 调用 `app.py` 中关联的 Python 函数，该函数可能反过来通过 `NetBoxClient` 调用 NetBox。
4. 结果在可用时通过 HTTP 传输流式返回。
> 注意：底层 HTTP 路径/形状由 FastMCP 运行时提供。希望连接的客户端应使用兼容的 MCP 客户端或支持读取分块/流式响应的 HTTP 客户端。
## 环境变量
在运行服务器之前设置这些变量：
- `NETBOX_URL` - 您的 NetBox 实例的基本 URL（默认为 `https://netbox.example.com`）。
- `NETBOX_TOKEN` - 具有读取权限的 NetBox API 令牌。
- `MCP_PORT` - FastMCP HTTP 传输的端口。如果未设置，默认为 `8000`。如果值不是有效的整数，服务器将退出并显示错误。
示例（macOS / zsh）：
```bash
export NETBOX_URL="https://netbox.example.com"
export NETBOX_TOKEN="0123456789abcdef0123456789abcdef01234567"
export MCP_PORT=8000
```
## 运行服务器
使用 Python 启动 MCP 服务器：
```bash
python3 app.py
```
服务器将绑定到配置的端口上的 0.0.0.0，并提供 FastMCP HTTP 传输。
## 包含的工具
`app.py` 为 NetBox 资源注册 MCP 工具。此仓库中包含的示例：
- `search_sites` — `dcim/sites/` 的搜索（支持部分/不区分大小写的名称查询）
- `get_site_details` — 站点查找
- `search_site_groups` — `dcim/site-groups/` 的搜索（支持 `name__ic`）
- `get_site_group_details` — 按 `id` 进行单个站点组查找
您可以按照仓库约定添加更多工具：每个 NetBox 资源都有一个 `search_<resource>` 和一个 `get_<resource>_details` 工具。
## 验证/测试
- 快速语法检查：
```bash
python3 -m py_compile app.py
```
- 启动服务器并使用支持流式传输的 HTTP 客户端（例如，`curl --no-buffer` 或自定义 MCP 客户端）连接到 FastMCP HTTP 传输并调用工具。
由于确切的 HTTP 请求形状（路径、标头和有效负载）由 FastMCP 运行时定义，客户端应在可用时优先使用现有的 MCP 客户端库。如果您正在构建自定义客户端，请确保它支持读取分块响应，以便可以增量消耗流式结果。
## 贡献
如果您添加工具，请遵循 `.github/copilot-instructions.md` 中记录的仓库约定：每个资源都应具有具有描述性文档字符串和一致参数映射的 `search_` 和 `get_` 工具。
## 许可证
该项目按原样提供。
MCP 市场