NetBox MCP服务器

NetBox MCP服务器

全面的读/写 模型上下文协议 NetBox网络文档和IPAM系统的服务器。正如我们的乐高鹦鹉吉祥物象征性地模仿人类语言一样，该服务器允许您通过支持MCP的LLM使用自然语言与NetBox基础设施“对话”。

✨ 主要特点

• 142+MCP工具：使用双工具模式架构完成DCIM、IPAM、租赁、附加、系统和虚拟化管理
• 🦜 Bridget-您的NetBox基础架构指南
  • 自动上下文检测 -智能环境检测（演示/暂存/生产）
  • 安全指南 -基于情境的操作建议
  • 基于角色的协助 -友好、专业的基础设施指导
  • 企业安全 -基于环境的安全等级自动分配
• 🔐 安全第一：内置的模拟运行模式、确认要求和审计日志
• 🏗️ 自我描述：使用REST API端点自动发现工具
• ⚡ 企业强化：生产就绪的秘密管理和结构化日志记录
• 📊 性能优化：基于TTL的缓存，性能提高33%以上
• 🔄 写入操作：具有幂等操作的完整读/写功能
• 🐳 Docker就绪：企业级集装箱化，带健康检查

🚀 快速开始

Docker（推荐）

docker run -d \
  --name netbox-mcp \
  -e NETBOX_URL="https://your-netbox.example.com" \
  -e NETBOX_TOKEN="your-api-token" \
  -e NETBOX_MCP_TRANSPORT="streamable-http" \
  -e NETBOX_MCP_HOST="0.0.0.0" \
  -e NETBOX_MCP_PORT="8000" \
  -p 8000:8000 \
  -p 8080:8080 \
  controlaltautomate/netbox-mcp:latest

MCP端点: http://localhost:8000/mcp
健康终点: http://localhost:8080/healthz （活性）， http://localhost:8080/readyz （准备就绪）

通过流式HTTP连接（MCP over HTTP）

此服务器同时支持 标准 （默认）和 流式HTTP 运输。

• 标准：非常适合Claude Desktop（客户端将服务器作为子进程启动）
• 流式HTTP：非常适合Docker/远程部署（服务器监听HTTP端口）

示例（Claude Code CLI）：

# Add the server as an HTTP MCP endpoint
claude mcp add --transport http netbox http://localhost:8000/mcp

提示：如果你运行容器，请保持 NETBOX_MCP_HOST=0.0.0.0 因此可以在容器外部访问MCP端点。

Python安装

git clone https://github.com/Deployment-Team/netbox-mcp.git
cd netbox-mcp
pip install .

Bridget汽车情境体验

为了在全自动上下文和角色指导下获得最佳的Bridget体验：

• 推荐：使用Claude Code CLI实现完整功能
• 替代：Claude Desktop（工具工作，有限的即时支持）

请参阅 Bridget文档 在我们的wiki上查看完整的使用指南。

📊 当前状态

版本：1.1.2-文档和版本同步！ ⭐

🎉 新增：管理IP套件：用于企业设备自动化的完整带外和主要IP管理工具：

• netbox_create_interface 和 mgmt_only BMC/iDRAC/控制台接口的参数
• 增强 netbox_update_device 和 oob_ip, primary_ip4, primary_ip6 支持
• netbox_set_primary_ip 具有灵活的IP解析和设备验证

✅ 生产就绪：所有管理IP工作流都针对NetBox 4.3.2进行了测试，并具有全面的错误修复和企业安全功能。

🔧 全面覆盖：六个领域的142多种生产就绪工具：

• DCIM工具（73）：完整的设备和基础架构生命周期管理，支持电源管理和管理IP
• 虚拟化工具（30）：完整的VM基础架构管理（新）⭐
• IPAM工具（16）：IP地址和网络管理与企业自动化
• 租赁工具（8）：分层组织的多租户资源管理
• 附加工具（2）：日记账分录和审计跟踪管理
• 系统工具（1）：健康监测和系统状态

🚀 发现工具: 23+ list_all_* 实现高效批量勘探的工具：

• netbox_list_all_devices, netbox_list_all_sites, netbox_list_all_racks, netbox_list_all_power_panels, netbox_list_all_power_feeds, netbox_list_all_power_outlets, netbox_list_all_power_cables, netbox_list_all_module_type_profiles （DCIM）
• netbox_list_all_prefixes, netbox_list_all_vlans, netbox_list_all_vrfs （ipad）
• netbox_list_all_tenants, netbox_list_all_tenant_groups （租赁）
• netbox_list_all_manufacturers, netbox_list_all_device_types, netbox_list_all_device_roles （设备管理）

🛡️ 企业基金会：具有注册表桥的防御性读验证写模式，确保100%的工具可访问性和冲突检测准确性。

⚙️ 配置

快速设置：设置所需的环境变量：

• NETBOX_URL：NetBox实例的完整URL
• NETBOX_TOKEN：来自NetBox的API令牌

MCP传输设置 （可选）：

• NETBOX_MCP_TRANSPORT: stdio （默认）或 streamable-http
• NETBOX_MCP_HOST：HTTP传输的绑定地址（默认值： 127.0.0.1)
• NETBOX_MCP_PORT：HTTP传输的绑定端口（默认值： 8000)
• NETBOX_MCP_PATH：MCP路径（默认值： /mcp)
• NETBOX_MCP_STATELESS_HTTP: true/false （默认值： false)
• NETBOX_MCP_JSON_RESPONSE: true/false （默认值： false)

🎯 工具配置文件（适用于Ollama和较小的LLM）

服务器支持 动态刀具轮廓 优化Ollama的qwen2.5:7b等较小模型的上下文使用。你可以从一个集中的子集开始，而不是用142多种工具来压倒模型。

可用配置文件:

配置:

# Via environment variable
NETBOX_TOOL_PROFILE=ipam

# Via netbox-mcp.yaml
tool_profile: "ipam"
enable_tool_profiles: true

动态配置文件切换:

AI模型可以在对话过程中切换配置文件：

User: "I need to manage IP addresses"
Model: → netbox_profile_activate(profile="ipam")
       ✅ IPAM tools now available

User: "List IPs in 10.0.0.0/24"  
Model: → netbox_list_ip_addresses(prefix="10.0.0.0/24")

配置文件元工具 （始终可用）：

• netbox_profile_list -列出可用配置文件
• netbox_profile_activate -切换到配置文件
• netbox_profile_current -显示活动配置文件和工具
• netbox_tool_search -按名称/描述搜索工具
• netbox_tool_help -使用指南

高级配置：使用YAML/TOML配置文件或其他环境变量来实现企业功能，如机密管理和结构化日志记录。

🔒 安全与企业特性

关键安全控制：此MCP服务器可以对NetBox数据执行写入操作：

• ✅ 临时运营：所有写入工具的设计都是幂等的
• ✅ 需要确认: confirm=True 所有写入操作的参数
• ✅ 全球模拟运行模式: NETBOX_DRY_RUN=true 用于测试
• ✅ 审计日志：全面记录所有操作
• ✅ 交易安全：具有回滚功能的原子操作

🏗️ 建筑亮点

革命性的双刀具模式

• 基础LLM架构：每个NetBox域都实现了“信息”工具（详细的单对象检索）和“list_all”工具（批量发现/探索）
• 综合过滤：所有列表工具都支持按站点、租户、状态和域特定条件进行筛选
• 汇总统计：丰富的汇总统计数据、细分和利用率指标，用于运营洞察
• 跨域集成：工具将DCIM、IPAM和Tenancy域与关系跟踪连接起来

革命性的自我描述服务器

• @mcp_tool装饰器：自动功能检查和元数据生成
• 插件架构：具有自动发现功能的模块化工具/子包
• 注册表桥模式：内部注册表和FastMCP接口之间的无缝连接
• 依赖注入：使用FastAPI的Depends（）系统进行干净的分离
• REST API端点: /api/v1/tools, /api/v1/execute, /api/v1/status

Bridget自动上下文层

Auto-Context Detection → Environment Assessment → Safety Assignment → Persona Guidance

企业安全与运营

• 秘密管理：Docker秘密、Kubernetes秘密、环境变量
• 结构化日志记录：JSON日志与ELK Stack、Splunk、Datadog兼容
• 性能监控：相关ID、操作时间、缓存统计信息

📚 文档

• 完整Wiki -带示例的综合文档
• api参考 -完整的工具文档
• 安装指南 -设置和部署
• Docker指南 -容器部署
• 企业展示 -真实世界的用例

📋 需求

• Python 3.10+
• NetBox 3.5+或更高版本（支持REST API v2.8+）
• 具有适当权限的有效NetBox API令牌

🚀 可用工具

系统工具 (1):

• netbox_health_check -全面健康检查

IPAM工具 (12):

• netbox_create_ip_address -创建IP地址分配
• netbox_find_available_ip -查找网络中的可用IP
• netbox_get_ip_usage -网络利用率统计
• netbox_create_prefix -创建网络前缀
• netbox_create_vlan -创建VLAN
• netbox_find_available_vlan_id -查找可用的VLAN ID
• netbox_create_vrf -创建VRF实例
• netbox_assign_mac_to_interface - 🆕 具有防御冲突检测的企业MAC地址管理
• netbox_find_next_available_ip - 🆕 具有跨域集成的原子IP预留
• netbox_get_prefix_utilization - 🆕 全面的容量规划报告
• netbox_provision_vlan_with_prefix - 🆕 原子VLAN/前缀协调
• netbox_assign_ip_to_interface - 🆕 跨域IPAM/DCIM集成

DCIM工具 (73):

• 核心基础设施 （17个工具）：

  • netbox_create_site, netbox_get_site_info -现场管理
  • netbox_create_rack, netbox_get_rack_elevation -机架管理
  • netbox_create_manufacturer -制造商管理
  • netbox_create_device_type, netbox_get_device_type_info, netbox_update_device_type, netbox_delete_device_type - 🆕 完整的设备类型CRUD
  • netbox_create_device_role -设备角色管理
  • netbox_create_device, netbox_get_device_info, netbox_update_device - 🆕 通过管理IP支持增强设备管理
  • netbox_install_module_in_device -设备组件安装
  • netbox_add_power_port_to_device -电力基础设施文件

• 管理和OOB IP套件 （3个工具）🆕:

  • netbox_create_interface - 🆕 通过以下方式创建界面 mgmt_only 支持BMC/iDRAC
  • netbox_set_primary_ip - 🆕 智能解析的主IP分配
  • 增强 netbox_update_device 和 oob_ip, primary_ip4, primary_ip6 参数

• 模块类型配置文件 （6个工具）🆕 NetBox 4.3.x:

  • netbox_create_module_type_profile, netbox_get_module_type_profile_info, netbox_list_all_module_type_profiles
  • netbox_update_module_type_profile, netbox_delete_module_type_profile, netbox_assign_module_type_profile

• 模块管理 （2个增强工具）🆕:

  • netbox_update_module_type, netbox_delete_module_type -完整的模块类型CRUD

• 电源管理基础设施 （19工具）🆕:

  • 电源面板 (5): netbox_create_power_panel, netbox_get_power_panel_info, netbox_list_all_power_panels, netbox_update_power_panel, netbox_delete_power_panel
  • 电源馈线 (5): netbox_create_power_feed, netbox_get_power_feed_info, netbox_list_all_power_feeds, netbox_update_power_feed, netbox_delete_power_feed
  • 电源插座 (5): netbox_create_power_outlet, netbox_get_power_outlet_info, netbox_list_all_power_outlets, netbox_update_power_outlet, netbox_delete_power_outlet
  • 电源连接 (4): netbox_create_power_cable, netbox_get_power_connection_info, netbox_list_all_power_cables, netbox_disconnect_power_cable

• 库存管理套件 （7个工具）：

  • netbox_add_inventory_item_template_to_device_type, netbox_list_inventory_item_templates_for_device_type
  • netbox_add_inventory_item_to_device, netbox_list_device_inventory, netbox_update_inventory_item
  • netbox_remove_inventory_item, netbox_bulk_add_standard_inventory

租赁工具 (8):

• netbox_create_contact_for_tenant - 🆕 基于角色分配的联系人管理
• netbox_onboard_new_tenant -通过联系人集成完成租户入职
• netbox_create_tenant_group -分层租户组织
• netbox_assign_resources_to_tenant -跨域资源分配
• netbox_get_tenant_resource_report -全面的租户资源报告
• netbox_list_all_tenants -批量租户发现
• netbox_list_all_tenant_groups -租户群体探索

附加工具 (2):

• netbox_create_journal_entry - 🆕 为任何NetBox对象创建审核跟踪条目
• netbox_list_all_journal_entries - 🆕 通过过滤发现批量日记账分录

虚拟化工具 (30) ⭐ 新:

• 集群 （5个工具）： netbox_create_cluster, netbox_get_cluster_info, netbox_list_all_clusters, netbox_update_cluster, netbox_delete_cluster
• 虚拟机 （5个工具）： netbox_create_virtual_machine, netbox_get_virtual_machine_info, netbox_list_all_virtual_machines, netbox_update_virtual_machine, netbox_delete_virtual_machine
• 集群类型 （5个工具）： netbox_create_cluster_type, netbox_get_cluster_type_info, netbox_list_all_cluster_types, netbox_update_cluster_type, netbox_delete_cluster_type
• 群集组 （5个工具）： netbox_create_cluster_group, netbox_get_cluster_group_info, netbox_list_all_cluster_groups, netbox_update_cluster_group, netbox_delete_cluster_group
• VM接口 （5个工具）： netbox_create_vm_interface, netbox_get_vm_interface_info, netbox_list_all_vm_interfaces, netbox_update_vm_interface, netbox_delete_vm_interface
• 虚拟磁盘 （5个工具）： netbox_create_virtual_disk, netbox_get_virtual_disk_info, netbox_list_all_virtual_disks, netbox_update_virtual_disk, netbox_delete_virtual_disk

🤝 贡献

该项目正在积极开发中。查看我们的 GitHub问题 用于：

• 当前的发展重点
• 功能请求和路线图
• Bug报告和讨论

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🔗 相关项目

• 企业网络自动化工具-生产就绪的MCP服务器
• NetBox -网络文档和IPAM应用程序

⚠️ 发展公告：这是一个具有写入功能的开发版本。始终使用适当的安全措施，并在非生产环境中进行测试。