Netbox MCP Rw

🚀 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：虚拟机、集群、集群组、集群类型、虚拟机接口等。

📦 安装指南

1. 克隆此仓库：

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

2. 安装依赖项：

# 使用 UV（推荐）
uv sync

# 或者使用 pip
pip install -e .

3. 设置环境变量：

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

4. 测试服务器：

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 服务器，欢迎帮助我们改进它：

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

路线图

• [ ] 使用 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 令牌具有适当的权限。谨慎使用批量操作，因为它们可能会同时修改多个对象。