AI导哈

网络基础设施查询服务器

NetBox MCP Server是一个只读的FastMCP服务器，通过模型上下文协议（MCP）向AI系统提供NetBox API功能，支持自然语言查询网络设备、站点、电路、VLAN、IP前缀和单个IP地址。

  • by chadkunsman
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 chadkunsman/netbox_mcp

使用说明

NetBox MCP服务器

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

概述

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

特性

设备管理

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

现场运营

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

电路管理

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

IP前缀管理

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

VLAN管理

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

IP 地址管理

  • 按地址、设备、接口、VRF和状态查询单个IP地址
  • 跟踪设备和接口的IP分配
  • 按IP角色筛选（环回、VIP、次要、任意播）
  • DNS主机名搜索和父前缀过滤
  • IPv4和IPv6支持

前缀与IP地址： 使用 前缀 子网/地址工具 池/VLAN到子网的映射，以及 IP地址 单个IP的工具 分配给设备/接口、DNS查找和IP角色过滤。

自然语言处理

  • 将自然语言查询智能解析为结构化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”

IP地址查询

  • “显示设备交换机01上的IP地址”
  • “查找所有环回地址”
  • “防火墙01分配了哪些IP？”
  • “显示主机名包含ntp的IP”
  • “列出VRF生产中的IPv4地址”

部署

运行层部署（推荐）

此项目旨在支持使用流式HTTP传输的Runlayer部署。通过自动扩展、监控和HTTPS端点部署到Runlayer的托管基础设施。

先决条件：

  • 本地运行的Docker（或Colima）
  • 运行层CLI(uvx runlayer)
  • Runlayer实例中的Admin API密钥

部署：

# Initialize deployment (creates runlayer.yaml)
uvx runlayer deploy init --secret <api-key> --host <runlayer-url>

# Configure runlayer.yaml with your environment variables, then deploy
uvx runlayer deploy --config runlayer.yaml --secret <api-key> --host <runlayer-url>

Colima用户，在部署命令前加上以下前缀：

DOCKER_HOST=unix://${HOME}/.colima/docker.sock uvx runlayer deploy ...

部署后，在Runlayer仪表板中将服务注册为MCP服务器，使其在MCP目录中可用。

配置： 这 runlayer.yaml 已预先配置用于：

  • ARM64架构（成本优化）
  • 8000端口 /mcp 端点路径
  • 可流式HTTP传输

每用户身份验证： 在托管的Runlayer部署中，每个用户 使用他们自己的NetBox API令牌进行身份验证。 NETBOX_TOKEN 因此 不 开始 runlayer.yaml --它是一个Runlayer 占位符，根据请求注入 这 x-rl-env-NETBOX_TOKEN 标头，并由服务器为该请求解析。 仅 NETBOX_URL 和 NETBOX_SSL_VERIFY 是部署范围的环境变量。

要配置它，请在连接器中 标头 字段（Runlayer仪表板）地图：

{ "x-rl-env-NETBOX_TOKEN": "{NETBOX_TOKEN}" }

并标记 NETBOX_TOKEN 占位符为必填项+机密。（在本地运行时 通过STDIO，令牌来自 NETBOX_TOKEN 环境变量。)

安装

本地运行（STDIO）

对于本地使用（例如使用像Claude Desktop这样的MCP客户端），请运行服务器 STDIO传输 uv。服务器使用包内导入，因此必须运行 从 src 目录通过 --directory:

MCP_TRANSPORT=stdio \
NETBOX_URL=https://your-netbox.example.com \
NETBOX_TOKEN=your_api_token \
NETBOX_SSL_VERIFY=true \
uv run --directory src python server.py

没有控制台脚本入口点；服务器直接通过以下方式启动 python server.py （本地通过STDIO）或作为HTTP服务（托管——请参阅 部署).

开发设置

对于开发和测试：

  1. 克隆存储库：

    git clone https://github.com/chadkunsman/netbox_mcp.git
cd netbox_mcp

  2. 在开发模式下安装：

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

  3. 设置环境变量：

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

Claude桌面配置

将此添加到您的Claude Desktop MCP配置中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上），将路径替换为您的 本地克隆：

{
  "mcpServers": {
    "netbox": {
      "command": "uv",
      "args": [
        "run", "--directory",
        "/absolute/path/to/netbox_mcp/src",
        "python", "server.py"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "NETBOX_URL": "https://your-netbox.example.com",
        "NETBOX_TOKEN": "your_api_token",
        "NETBOX_SSL_VERIFY": "true"
      }
    }
  }
}

笔记： MCP_TRANSPORT=stdio 是必需的（服务器默认为HTTP）。 Claude Desktop以最小的 PATH，所以如果 uv 未找到，请使用其 绝对路径 command （例如。 /opt/homebrew/bin/uv).重新启动克劳德桌面 编辑配置后。

自动化测试

运行pytest测试套件（集成测试查询真实的NetBox实例，因此 NETBOX_URL/NETBOX_TOKEN 必须设置，例如通过本地 .env):

# Run the full suite
uv run pytest tests/ -v

# Run only the integration tests
uv run pytest tests/test_mcp_tools.py -v

# Run with coverage
uv run pytest tests/ --cov=src

使用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连接：

  • NETBOX_URL：NetBox实例的URL（例如。，https://netbox.example.com)--必填
  • NETBOX_TOKEN：具有读取权限的API令牌。本地/STDIO使用所需；在托管的Runlayer部署中，它是通过以下方式为每个用户提供的 x-rl-env-NETBOX_TOKEN 改为标题（请参见 部署)
  • NETBOX_SSL_VERIFY：是否验证SSL证书（true/false，默认为true）

运输 （启动服务器时使用）：

  • MCP_TRANSPORT: stdio 供当地使用，或 http （流式HTTP）用于托管/Runlayer。默认为 http
  • MCP_HOST：为HTTP传输绑定主机（默认 0.0.0.0)
  • MCP_PORT：绑定HTTP传输端口（默认 8000)

项目结构

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
│   │   └── ip_addresses.py # IP address-related tools
│   ├── models/            # Pydantic models
│   ├── utils/             # Shared utility functions
│   └── config/            # Configuration
│       └── netbox.py      # NetBox client configuration
├── tests/                 # Pytest test suite
│   ├── test_mcp_tools.py  # Integration tests
│   └── conftest.py        # Test fixtures
└── docs/                  # NetBox-specific documentation

许可证

MIT许可证

贡献

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

相关 MCP