金大哥 - netbox-mcp-rw MCP 详情

article

README

🚀 NetBox MCP 读写服务器

这是首个具备完整读写功能的 NetBox 模型上下文协议（MCP）服务器。与现有的只读 NetBox MCP 实现不同，该服务器提供全面的 CRUD（创建、读取、更新、删除）操作，让你不仅可以查询 NetBox 数据，还能通过支持 MCP 的大语言模型（LLMs）直接修改数据。

🚀 快速开始

本服务器是首个支持对 NetBox 进行读写操作的 MCP 服务器，能提供全面的 CRUD 操作，支持批量处理，覆盖所有主要的 NetBox 模型，并且具备生产就绪的特性。

✨ 主要特性

特殊之处

首个支持读写的 NetBox MCP：唯一允许对 NetBox 进行读写操作的 MCP 服务器。
完整的 CRUD 操作：可创建、读取、更新和删除任何 NetBox 对象类型。
批量操作：能高效地一次性处理多个对象。
全面覆盖：支持所有主要的 NetBox 模型（如 DCIM、IPAM、Circuits、Virtualization 等）。
生产就绪：具备完善的错误处理、验证和安全实践。

读取操作

列出并过滤任何 NetBox 对象类型。
获取特定对象的详细信息。
访问更改历史和审计记录。
具备高级过滤和搜索功能。

写入操作

创建新的设备、IP 地址、站点、机架等。
更新现有对象的属性。
删除对象（具备适当的保护措施）。
支持批量创建、更新和删除操作。

支持的对象类型

DCIM（设备和基础设施）：设备、设备类型、设备角色、制造商、站点、位置、机架、机架角色、电缆、接口、电源端口、控制台端口、平台、区域、虚拟机箱。
IPAM（IP 地址管理）：IP 地址、前缀、VLAN、VRF、自治系统编号（ASNs）、聚合、服务、角色、区域互联网注册机构（RIRs）、路由目标。
Circuits：电路、电路类型、提供商、电路终端、提供商网络。
Virtualization：虚拟机、集群、集群组、集群类型、虚拟机接口等。

📦 安装指南

克隆此仓库：

git clone https://github.com/alexkiwi1/netbox-mcp-rw.git
cd netbox-mcp-rw

安装依赖项：

# 使用 UV（推荐）
uv sync

# 或者使用 pip
pip install -e .

设置环境变量：

export NETBOX_URL="https://your-netbox-instance.com/"
export NETBOX_TOKEN="your-api-token"

测试服务器：

NETBOX_URL=https://netbox.example.com/ NETBOX_TOKEN=<your-token> uv run server.py

📚 详细文档

MCP 客户端配置

Claude 桌面版（Mac/Windows）

在你的 Claude 桌面版配置中添加以下内容：

{
  "mcpServers": {
    "netbox-rw": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/netbox-mcp-rw",
        "run",
        "server.py"
      ],
      "env": {
        "NETBOX_URL": "https://your-netbox-instance.com/",
        "NETBOX_TOKEN": "your-api-token"
      }
    }
  }
}

其他 MCP 客户端

此服务器可与任何兼容 MCP 的客户端配合使用。根据客户端的要求调整命令和参数。

可用工具

设备管理

netbox_get_objects - 列出/过滤任何对象类型。
netbox_get_object_by_id - 获取特定对象的详细信息。
netbox_create_object - 创建新对象。
netbox_update_object - 更新现有对象。
netbox_delete_object - 删除对象。
netbox_bulk_create_objects - 批量创建操作。
netbox_bulk_update_objects - 批量更新操作。
netbox_bulk_delete_objects - 批量删除操作。

审计与历史

netbox_get_changelogs - 访问更改历史和审计记录。

安全特性

API 令牌存储在环境变量中（绝不硬编码）。
默认启用 SSL/TLS 验证。
具备完善的错误处理和验证。
通过 NetBox 内置的更改日志保留审计记录。

要求

Python 3.13 及以上版本。
具备 API 访问权限的 NetBox 实例。
具有适当权限的有效 NetBox API 令牌。

贡献

这是首个支持读写的 NetBox MCP 服务器，欢迎帮助我们改进它：

分叉仓库。
创建功能分支。
进行更改。
添加测试。
提交拉取请求。

路线图

[ ] 使用 Pydantic 模型添加输入验证。
[ ] 实现缓存以提高性能。
[ ] 添加异步支持。
[ ] 创建全面的测试套件。
[ ] 增加对自定义字段和插件的支持。

💻 使用示例

读取数据

"显示纽约数据中心的所有活动设备"
"列出 10.0.1.0/24 子网中的可用 IP 地址"
"上周对设备做了哪些更改？"

写入数据

"在纽约数据中心 1 号站点的 R42 机架中创建一台名为 'web-01' 的新服务器"
"将 IP 地址 192.168.1.100/24 添加到设备 'firewall-01'"
"将设备 'switch-01' 的状态更新为维护模式"
"在总部站点创建一个名为 'DMZ' 的新 VLAN 100"

批量操作

"创建 10 台新服务器，名称从 web-01 到 web-10"
"将所有思科设备的平台更新为 'ios'"
"删除已停用子网中的所有 IP 地址"

📄 许可证

本项目采用 Apache 2.0 许可证 - 详情请参阅 LICENSE 文件。

致谢

本项目基于优秀的 FastMCP 框架和 NetBox 全面的 REST API 构建。

⚠️ 重要提示

此服务器具备写入功能。请先在开发环境中进行测试，并确保你的 API 令牌具有适当的权限。谨慎使用批量操作，因为它们可能会同时修改多个对象。

netbox-mcp-rw