NetBox MCP Server

NetBox MCP Server

⚠️ v1.0.0 中的破坏性变更：项目结构已更改。 如果从 v0.1.0 升级，请更新配置：

• 将 uv run server.py 改为 uv run netbox-mcp-server
• 更新 Claude Desktop/Code 配置，使用 netbox-mcp-server 替代 server.py
• Docker 用户：使用更新后的 CMD 重新构建镜像
• 完整详情请参阅 CHANGELOG.md

这是一个面向 NetBox 的简单只读 Model Context Protocol 服务。它支持你通过支持 MCP 的大模型直接与 NetBox 中的数据交互。

此服务有意保持简单：易于上手、不易误用（默认只读，没有插件扩展接口），也易于分叉和改造。对于需要项目范围之外功能的用户，基于 Apache 2.0 许可证进行分叉是首选方案。

社区

如需聊天、交流用例和讨论 MCP，请加入 NetBox 社区 netdev.chat。#ai 频道适合讨论 MCP 集成、提问和分享用例。与此服务相关的 Bug 和功能建议请提交至 issues。

工具

工具	描述
get_objects	根据类型和筛选条件检索 NetBox 核心对象
get_object_by_id	根据 ID 获取特定 NetBox 对象的详细信息
get_changelogs	根据筛选条件检索变更历史记录（审计跟踪）

注意：NetBox 核心对象类型始终可用。插件对象类型可自动发现。请参阅插件对象类型发现。高级功能（GraphQL、动态模型发现等）有意不在项目范围内。完整的范围说明及原因请参阅 CONTRIBUTING.md。

使用方法

1. 在 NetBox 中创建一个只读 API 令牌，并授予工具足够的权限，以便访问你希望通过 MCP 提供的数据。

2. 安装依赖项：

   # 使用 UV（推荐）
   uv sync
   
   # 或使用 pip
   pip install -e .
   

3. 验证服务能否运行：NETBOX_URL=https://netbox.example.com/ NETBOX_TOKEN=<your-api-token> uv run netbox-mcp-server

4. 将 MCP 服务添加到你的大模型客户端。以下是一些使用 Claude 的示例。

Claude Code

Stdio 传输（默认）

使用 claude mcp add 命令添加服务：

claude mcp add --transport stdio netbox \
  --env NETBOX_URL=https://netbox.example.com/ \
  --env NETBOX_TOKEN=<your-api-token> \
  -- uv --directory /path/to/netbox-mcp-server run netbox-mcp-server

重要说明：

• 将 /path/to/netbox-mcp-server 替换为本地克隆仓库的绝对路径
• -- 分隔符用于区分 Claude Code 标志和服务命令
• 使用 --scope project，通过版本控制中的 .mcp.json 共享配置
• 使用 --scope user，使其在所有项目中可用（默认值为 local）

添加后，可在 Claude Code 中使用 /mcp，或在终端中使用 claude mcp list 进行验证。

HTTP 传输

使用 HTTP 传输时，请先手动启动服务：

# Start the server with HTTP transport (using .env or environment variables)
NETBOX_URL=https://netbox.example.com/ \
NETBOX_TOKEN=<your-api-token> \
TRANSPORT=http \
uv run netbox-mcp-server

然后将正在运行的服务添加到 Claude Code：

# Add the HTTP MCP server (note: URL must include http:// or https:// prefix)
claude mcp add --transport http netbox http://127.0.0.1:8000/mcp

重要说明：

• URL 必须包含协议前缀（http:// 或 https://）
• 使用 HTTP 传输时，默认端点为 /mcp
• Claude Code 连接前，服务必须已在运行
• 使用 claude mcp list 验证连接——服务名称旁应显示 ✓

Claude Desktop

将服务配置添加到 Claude Desktop 配置文件中。在 Mac 上，编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

在 Windows 上，请使用实例的完整转义路径，例如 C:\\Users\\myuser\\.local\\bin\\uv 和 C:\\Users\\myuser\\netbox-mcp-server。 如需详细的故障排除说明，请参阅 MCP quickstart。

5. 在大模型客户端中使用这些工具。例如：

> Get all devices in the 'Equinix DC14' site
...
> Tell me about my IPAM utilization
...
> What Cisco devices are in my network?
...
> Who made changes to the NYC site in the last week?
...
> Show me all configuration changes to the core router in the last month

字段筛选（令牌优化）

netbox_get_objects() 和 netbox_get_object_by_id() 均支持可选的 fields 参数，以减少令牌用量：

# Without fields: ~5000 tokens for 50 devices
devices = netbox_get_objects("devices", {"site": "datacenter-1"})

# With fields: ~500 tokens (90% reduction)
devices = netbox_get_objects(
    "devices", {"site": "datacenter-1"}, fields=["id", "name", "status", "site"]
)

常见字段模式：

• 设备： ['id', 'name', 'status', 'device_type', 'site', 'primary_ip4']
• IP 地址： ['id', 'address', 'status', 'dns_name', 'description']
• 接口： ['id', 'name', 'type', 'enabled', 'device']
• 站点： ['id', 'name', 'status', 'region', 'description']

fields 参数使用 NetBox 的原生字段筛选功能。详情请参阅 NetBox API 文档。

配置

服务支持多种配置来源，优先级如下（从高到低）：

1. 命令行参数（优先级最高）
2. 环境变量
3. 项目根目录中的 .env 文件
4. 默认值（优先级最低）

配置参考

设置	类型	默认值	必需	描述
NETBOX_URL	URL	-	是	NetBox 实例的基础 URL（例如，https://netbox.example.com/）
NETBOX_TOKEN	String	-	是	用于身份验证的 API 令牌
TRANSPORT	stdio | http	stdio	否	MCP 传输协议
HOST	String	127.0.0.1	使用 HTTP 时	HTTP 服务的主机地址
PORT	Integer	8000	使用 HTTP 时	HTTP 服务的端口
MCP_AUTH_TOKEN	String	-	否	HTTP 端点要求提供的 Bearer 令牌。未设置时，HTTP 传输不进行身份验证。客户端需发送 Authorization: Bearer <token>。
VERIFY_SSL	Boolean	true	否	是否验证 SSL 证书
ENABLE_PLUGIN_DISCOVERY	Boolean	false	否	启动时自动发现插件对象类型
LOG_LEVEL	DEBUG | INFO | WARNING | ERROR | CRITICAL	INFO	否	日志详细程度

传输示例

Stdio 传输（Claude Desktop/Code）

在本地使用 Claude Desktop 或 Claude Code，并通过 stdio 传输时：

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

HTTP 传输（Web 客户端）

Web MCP 客户端使用 HTTP/SSE 传输时：

# Using environment variables
export NETBOX_URL=https://netbox.example.com/
export NETBOX_TOKEN=<your-api-token>
export TRANSPORT=http
export HOST=127.0.0.1
export PORT=8000

uv run netbox-mcp-server

# Or using CLI arguments
uv run netbox-mcp-server \
  --netbox-url https://netbox.example.com/ \
  --netbox-token <your-api-token> \
  --transport http \
  --host 127.0.0.1 \
  --port 8000

.env 文件示例

在项目根目录中创建一个 .env 文件：

# Core NetBox Configuration
NETBOX_URL=https://netbox.example.com/
NETBOX_TOKEN=your_api_token_here

# Transport Configuration (optional, defaults to stdio)
TRANSPORT=stdio

# HTTP Transport Settings (only used if TRANSPORT=http)
# HOST=127.0.0.1
# PORT=8000
# Bearer token required on the HTTP endpoint. When unset, the endpoint is unauthenticated.
# MCP_AUTH_TOKEN=a-strong-random-token

# Security (optional, defaults to true)
VERIFY_SSL=true

# Plugin Discovery (optional, defaults to false)
# ENABLE_PLUGIN_DISCOVERY=true

# Logging (optional, defaults to INFO)
LOG_LEVEL=INFO

CLI 参数

所有配置选项都可以通过 CLI 参数覆盖：

uv run netbox-mcp-server --help

# Common examples:
uv run netbox-mcp-server --log-level DEBUG --no-verify-ssl  # Development
uv run netbox-mcp-server --transport http --port 9000       # Custom HTTP port

Docker 用法

预构建镜像（Docker Hub）

每次发布带标签的版本时，都会将预构建的多架构镜像（linux/amd64、linux/arm64）发布到 Docker Hub：

docker pull netboxlabs/netbox-mcp-server:latest

在生产环境中请固定到特定版本。latest 标签指向最新发布版本，可能会随时变更，恕不另行通知。可在发布页面查看可用版本：

docker pull netboxlabs/netbox-mcp-server:<X.Y.Z>   # exact version
docker pull netboxlabs/netbox-mcp-server:<X.Y>     # latest within a minor
docker pull netboxlabs/netbox-mcp-server:<X>       # latest within a major

验证镜像来源（可选，但建议执行）。 镜像使用 cosign 签名（通过 GitHub OIDC 实现无密钥签名），并附带 SLSA 构建来源证明：

cosign verify \
  --certificate-identity-regexp '^https://github.com/netboxlabs/netbox-mcp-server/' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  netboxlabs/netbox-mcp-server:<tag>

标准 Docker 镜像

在容器中构建并运行 NetBox MCP 服务：

# Build the image
docker build -t netbox-mcp-server:latest .

# Run with HTTP transport (required for Docker containers)
docker run --rm \
  -e NETBOX_URL=https://netbox.example.com/ \
  -e NETBOX_TOKEN=<your-api-token> \
  -e TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e MCP_AUTH_TOKEN=<a-strong-random-token> \
  -p 8000:8000 \
  netbox-mcp-server:latest

注意： Docker 容器必须设置 TRANSPORT=http，因为 stdio 传输无法在容器化环境中工作。

⚠️ 安全： 除非设置 MCP_AUTH_TOKEN，否则 HTTP 传输没有身份验证。绑定到 HOST=0.0.0.0 会将令牌可访问的所有 NetBox 数据开放给任何能够连接该端口的人。请设置强度足够的 MCP_AUTH_TOKEN（客户端随后发送 Authorization: Bearer <token>），并在将服务暴露到网络之前，通过反向代理或网关终止 TLS。通过纯 HTTP 发送的 Bearer 令牌可能会被截获，因此实际部署必须使用 TLS。

连接到主机上的 NetBox：

如果 NetBox 实例运行在主机上（而不是容器中），在 macOS 和 Windows 上需要使用 host.docker.internal，而不是 localhost：

# For NetBox running on host (macOS/Windows)
docker run --rm \
  -e NETBOX_URL=http://host.docker.internal:18000/ \
  -e NETBOX_TOKEN=<your-api-token> \
  -e TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e MCP_AUTH_TOKEN=<a-strong-random-token> \
  -p 8000:8000 \
  netbox-mcp-server:latest

注意： 在 Linux 上，可以改用 --network host，或直接使用主机的 IP 地址。

使用其他配置选项：

docker run --rm \
  -e NETBOX_URL=https://netbox.example.com/ \
  -e NETBOX_TOKEN=<your-api-token> \
  -e TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e MCP_AUTH_TOKEN=<a-strong-random-token> \
  -e LOG_LEVEL=DEBUG \
  -e VERIFY_SSL=false \
  -p 8000:8000 \
  netbox-mcp-server:latest

MCP 客户端可通过 http://localhost:8000/mcp 访问该服务。你可以使用偏好的方式连接。

插件对象类型发现

默认情况下，只有 NetBox 核心对象类型可用。如果 NetBox 实例安装了插件（例如 netbox-dns、netbox-inventory），可以启用自动发现，以便使用这些插件的对象类型。

启用发现

设置 ENABLE_PLUGIN_DISCOVERY 环境变量，或使用 --enable-plugin-discovery CLI 标志：

# Via environment variable
ENABLE_PLUGIN_DISCOVERY=true uv run netbox-mcp-server

# Via CLI flag
uv run netbox-mcp-server --enable-plugin-discovery

# In Claude Desktop config
{
    "mcpServers": {
        "netbox": {
            "command": "uv",
            "args": ["--directory", "/path/to/netbox-mcp-server", "run", "netbox-mcp-server"],
            "env": {
                "NETBOX_URL": "https://netbox.example.com/",
                "NETBOX_TOKEN": "<your-api-token>",
                "ENABLE_PLUGIN_DISCOVERY": "true"
            }
        }
    }
}

工作原理

启动时，服务会查询 NetBox 的 core/object-types API 端点（对于 NetBox < 4.4，则回退到 extras/object-types），以查找所有已安装且具有 REST API 端点的插件模型。随后，这些模型会与核心类型一同合并到运行时类型注册表中。

发现的插件类型使用 app_label.model 命名约定（例如 netbox_dns.zone、netbox_inventory.asset），并可与所有现有工具（netbox_get_objects、netbox_get_object_by_id、netbox_search_objects）配合使用。

要求

• NetBox 4.2 或更高版本
• API 令牌必须具有对 object-types 端点的读取权限
• 插件模型必须提供 REST API 端点，才能被发现

失败时的行为

如果发现因任何原因失败（网络错误、权限不足、NetBox 版本不受支持），服务会记录警告，并仅使用核心类型继续运行。这样无论发现结果如何，服务都能成功启动。

开发

欢迎贡献！提交新功能建议前，请阅读 CONTRIBUTING.md。我们建议先提交 issue 进行讨论，以确认功能范围是否合适。

如果你的使用场景需要的功能超出本项目范围，可以在 Apache 2.0 许可下分叉项目；我们会积极支持这种做法。

许可证

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