网络盒MCP服务器

Name: 网络盒MCP服务器
Author: netboxlabs

作者：netboxlabs98 星标更新：2025-11-01

安装使用来源：spider==github.com

项目介绍

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

这是一个简单的只读 Model Context Protocol 服务器用于 NetBox。它允许您通过支持 MCP 的大型语言模型（LLMs）直接与 NetBox 中的数据进行交互。

工具

工具	描述
get_objects	根据类型和过滤器检索 NetBox 核心对象
get_object_by_id	根据 ID 获取特定 NetBox 对象的详细信息
get_changelogs	根据过滤器检索变更历史记录（审计轨迹）

注意：目前支持的对象类型集是显式定义并限制在核心 NetBox 对象上，并且不会与插件中的对象类型一起工作。

使用方法

在 NetBox 中创建一个具有足够权限的只读 API 令牌，以便工具可以访问您希望通过 MCP 提供的数据。

安装依赖项：

# 使用 UV（推荐）
uv sync

# 或者使用 pip
pip install -e .

验证服务器能否运行：NETBOX_URL=https://netbox.example.com/ NETBOX_TOKEN=<your-api-token> uv run netbox-mcp-server
将 MCP 服务器添加到您的 LLM 客户端。以下是一些使用 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 运输方式，首先手动启动服务器：

# 使用 .env 或环境变量启动带有 HTTP 运输方式的服务器
NETBOX_URL=https://netbox.example.com/ \
NETBOX_TOKEN=<your-api-token> \
TRANSPORT=http \
uv run netbox-mcp-server

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

# 添加 HTTP MCP 服务器（注意：URL 必须包含 http:// 或 https:// 前缀）
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 快速入门。

在您的 LLM 客户端中使用这些工具。例如：

> 获取“Equinix DC14”站点的所有设备
...
> 告诉我关于我的 IPAM 利用情况
...
> 我网络中有哪些 Cisco 设备？
...
> 在过去一周内谁对 NYC 站点进行了更改？
...
> 显示过去一个月内对核心路由器的所有配置更改

字段过滤（令牌优化）

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

# 不带字段：50 个设备约 5000 个令牌
devices = netbox_get_objects('devices', {'site': 'datacenter-1'})

# 带字段：约 500 个令牌（减少了 90%）
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 文档。

配置

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

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

配置参考

设置	类型	默认值	是否必需	描述
`NETBOX_URL`	URL	-	是	您的 NetBox 实例的基本 URL（例如，https://netbox.example.com/）
`NETBOX_TOKEN`	字符串	-	是	认证的 API 令牌
`TRANSPORT`	`stdio` \| `http`	`stdio`	否	MCP 传输协议
`HOST`	字符串	`127.0.0.1`	如果是 HTTP	HTTP 服务器的主机地址
`PORT`	整数	`8000`	如果是 HTTP	HTTP 服务器的端口
`VERIFY_SSL`	布尔值	`true`	否	是否验证 SSL 证书
`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 传输方式：

# 使用环境变量
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

# 或使用 CLI 参数
uv run netbox-m
cp-server \
  --netbox-url https://netbox.example.com/ \
  --netbox-token <your-api-token> \
  --transport http \
  --host 127.0.0.1 \
  --port  8000

示例 .env 文件

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

# 核心 NetBox 配置
NETBOX_URL=https://netbox.example.com/
NETBOX_TOKEN=your_api_token_here

# 传输配置（可选，默认为 stdio）
TRANSPORT=stdio

# HTTP 传输设置（仅当 TRANSPORT=http 时使用）
# HOST=127.0.0.1
# PORT=8000

# 安全性（可选，默认为 true）
VERIFY_SSL=true

# 日志（可选，默认为 INFO）
LOG_LEVEL=INFO

CLI 参数

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

uv run netbox-mcp-server --help

# 常见示例：
uv run netbox-mcp-server --log-level DEBUG --no-verify-ssl  # 开发
uv run netbox-mcp-server --transport http --port 9000       # 自定义 HTTP 端口

Docker 使用

标准 Docker 镜像

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

# 构建镜像
docker build -t netbox-mcp-server:latest .

# 使用 HTTP 传输方式运行（Docker 容器所需）
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 \
  -p 8000:8000 \
  netbox-mcp-server:latest

注意：由于 stdio 传输方式在容器化环境中不起作用，Docker 容器需要 TRANSPORT=http。

连接到主机上的 NetBox：

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

# 对于在主机上运行的 NetBox（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 \
  -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 LOG_LEVEL=DEBUG \
  -e VERIFY_SSL=false \
  -p 8000:8000 \
  netbox-mcp-server:latest

服务器将在 http://localhost:8000/mcp 对 MCP 客户端可用。您可以使用您喜欢的方法连接到它。

开发

欢迎贡献！请打开问题或提交 PR。

许可证

此项目根据 Apache 2.0 许可证发布。详情请参阅 LICENSE 文件。