Net Box MCP Server

NetBox MCP服务器

一个全面的只读FastMCP服务器，通过模型上下文协议（MCP）向人工智能系统公开NetBox API功能。

概述

此项目实现了一个只读MCP服务器，该服务器提供了与NetBox基础架构数据交互的全面工具。它支持对网络设备、站点、电路、VLAN和IP前缀的自然语言查询，使AI助手更容易检索和呈现网络基础设施信息，而不允许对NetBox数据进行任何修改。

特性

设备管理

• 使用结构化筛选器查询NetBox设备
• 按特定名称搜索设备
• 使用自然语言询问设备
• 支持按站点、角色、状态、制造商等进行筛选

现场作业

• 列出所有可用站点的状态和地区信息
• 获取全面的现场详细信息，包括设备和机架数量
• 跨所有资源类型的基于站点的筛选

电路管理

• 按供应商、类型、状态和端接地点查询电路
• 使用自然语言搜索电路
• 轨道电路端子（A侧和Z侧）
• 按电路ID模式过滤

IP前缀管理

• 按站点、VRF、租户、状态和角色查询IP前缀
• 支持IPv4和IPv6地址族
• VLAN关联和过滤
• 前缀池管理
• CIDR符号模式匹配

VLAN管理

• 按名称、VID（VLAN ID）、站点、组、租户、角色和状态查询VLAN
• VLAN名称和描述的真实子字符串匹配
• 跨VLAN属性的跨字段搜索
• 支持VLAN组和租户组织

自然语言处理

• 将自然语言查询智能解析为结构化API调用
• 站点、角色、提供者和电路类型的模糊匹配
• 跨领域搜索功能
• 用户友好的错误消息和建议

查询示例

设备查询

• “显示SF1站点的所有设备”
• “列出所有活动防火墙”
• “告诉我有关设备sf1.as1的信息”
• “查找所有ION设备”
• “显示纽约市位置的开关”

网站查询

• “列出所有可用站点”
• “告诉我关于SF1网站的情况”
• “显示丹佛的网站信息”

电路查询

• “给我看看Zayo的电路”
• “列出SF1处的互联网电路”
• “查找电路CID-12345”
• “显示活动MPLS电路”

IP前缀查询

• “在SF1处显示IPv4前缀”
• “列出所有/24个子网”
• “查找VLAN 100中的前缀”
• “显示前缀池”

VLAN查询

• “显示VLAN 100”
• “列出SF1站点的所有VLAN”
• “查找名称中包含'90'的VLAN”
• “显示租户ABC的活动VLAN”
• “获取所有生产VLAN”

安装

使用uvx（推荐）

使用此MCP服务器的最简单方法是 uvx:

# Install and run with environment variables
uvx --from . \
  --with-editable . \
  --env NETBOX_URL=https://your-netbox.example.com \
  --env NETBOX_TOKEN=your_api_token \
  --env NETBOX_SSL_VERIFY=true \
  netbox-mcp-server

开发设置

对于开发和测试：

1. 克隆存储库：

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

1. 在开发模式下安装：

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -e .

1. 设置环境变量：

   export NETBOX_URL=https://your-netbox.example.com
   export NETBOX_TOKEN=your_api_token
   export NETBOX_SSL_VERIFY=true

Claude桌面配置

将此添加到您的Claude Desktop MCP配置中：

{
  "mcpServers": {
    "netbox": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/yourusername/netbox-mcp.git",
        "--with-editable", ".",
        "netbox-mcp-server"
      ],
      "env": {
        "NETBOX_URL": "https://your-netbox.example.com",
        "NETBOX_TOKEN": "your_api_token",
        "NETBOX_SSL_VERIFY": "true"
      }
    }
  }
}

使用MCPTools进行测试

对于开发和测试，请使用MCPTools：

# List all available tools 
mcp tools uv run --directory src python server.py

# Call a specific tool with parameters
mcp call get_device --params '{"name":"my-device-01"}' uv run --directory src python server.py

# Start interactive testing shell
mcp shell uv run --directory src python server.py

# View server logs during testing
mcp tools --server-logs uv run --directory src python server.py

配置

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

• NETBOX_URL：NetBox实例的URL（例如。，https://netbox.example.com)
• NETBOX_TOKEN：具有适当权限的API令牌
• NETBOX_SSL_VERIFY：是否验证SSL证书（真/假）
• DEBUG：启用调试模式（真/假）
• LOG_LEVEL：日志记录级别（信息、调试、警告、错误）

项目结构

netbox-mcp/
├── src/
│   ├── server.py          # Main MCP server implementation
│   ├── tools/             # Tool definitions
│   │   ├── devices.py     # Device-related tools
│   │   ├── sites.py       # Site-related tools
│   │   ├── circuits.py    # Circuit-related tools
│   │   ├── prefixes.py    # IP prefix-related tools
│   │   └── vlans.py       # VLAN-related tools
│   ├── models/            # Pydantic models
│   │   ├── device.py      # Device-related models
│   │   ├── site.py        # Site-related models
│   │   ├── circuit.py     # Circuit-related models
│   │   ├── prefix.py      # IP prefix-related models
│   │   └── vlan.py        # VLAN-related models
│   └── config/            # Configuration
│       └── netbox.py      # NetBox client configuration
├── docs/                  # Documentation
└── tests/                 # Test files

许可证

MIT许可证

贡献

欢迎投稿！请随时提交拉取请求。