前言：为什么要用 MCP 服务器

在传统方式中，如果我们希望程序或自动化脚本获取 NetBox 中的数据，通常会直接调用 NetBox REST API。这种方式稳定、直接，也非常适合固定流程的系统集成，例如资产同步、批量导出、自动化巡检等。

但当我们希望让 AI 助手或 Agent 参与网络运维时，直接调用 REST API 就不够方便了。NetBox 的数据模型较为复杂，涉及站点、机柜、设备、接口、IP 地址、VLAN、前缀、线缆等多个对象。AI 如果直接面对原始 REST API，需要理解大量接口路径、查询参数、分页逻辑和返回字段，这不仅增加了集成复杂度，也容易造成调用不稳定或上下文浪费。

MCP，全称 Model Context Protocol，即模型上下文协议。它的作用是为 AI 模型提供一种标准化方式，让模型能够安全、统一地访问外部系统、工具和数据源。通过 MCP 服务器，我们可以把 NetBox 的 REST API 封装成一组更适合 AI 使用的工具，例如查询设备、查找可用 IP、获取接口信息、分析设备连接关系等。这样，AI 不需要直接理解 NetBox 底层 API，只需要调用语义清晰的 MCP 工具，就可以完成对 NetBox 数据的查询和分析。

使用 netbox-mcp-server 的核心价值在于：它不是替代 NetBox API，而是在 NetBox API 之上增加了一层面向 AI 的适配层。这个适配层可以隐藏底层接口细节，整理返回结果，减少无关字段，并为 AI 提供更容易理解的上下文。对于网络运维人员来说，这意味着可以用自然语言向 AI 提问，例如“某个站点有哪些交换机”“某个网段还有多少可用 IP”“这台设备连接到了哪里”，而不必手动编写 API 请求或解析复杂 JSON。

此外，MCP 服务器还可以作为安全边界。相比直接把 NetBox API Token 暴露给 AI 客户端，通过 MCP 服务器可以集中管理访问凭据、限制可用工具、控制读写权限，并在必要时增加审计、脱敏和访问控制。这对于生产环境中的网络资产数据尤为重要。

因此，在构建 AI 运维助手、网络 Copilot 或自动化 Agent 时，部署一个 NetBox MCP 服务器可以显著降低集成复杂度，让 AI 以更标准、更安全、更自然的方式使用 NetBox 数据。简单来说，NetBox REST API 更适合传统程序调用，而 netbox-mcp-server 更适合让 AI 助手理解、查询和分析 NetBox。

Netbox 系列文章：https://songxwn.com/categories/NetBox/

环境介绍

Rocky Linux 9 （理论上也适用于RHEL系列的7-9版本）

南京大学镜像源ISO镜像下载：https://mirror.nju.edu.cn/rocky/9/isos/x86_64/Rocky-9-latest-x86_64-minimal.iso

环境配置

1
2
3
4
5
systemctl disable --now firewalld
sed -i 's/^SELINUX=enforcing$/SELINUX=disabled/' /etc/selinux/config && setenforce 0
# 关闭防火墙和SELinux。
dnf install tree vim bash-completion tar git -y
# 安装一些工具，用于之后的部署

Docker-CE 环境安装

1
2
3
4
yum install -y yum-utils
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sed -i 's+https://download.docker.com+https://mirrors.tuna.tsinghua.edu.cn/docker-ce+' /etc/yum.repos.d/docker-ce.repo
yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

参考清华大学源：https://mirrors.tuna.tsinghua.edu.cn/help/docker-ce/

Docker国内镜像加速器配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
sudo mkdir -p /etc/docker
# 创建文件夹
sudo tee /etc/docker/daemon.json <<-'EOF'
{
    "registry-mirrors": [
        "https://docker.1ms.run",
        "https://docker.1panel.live",
        "https://docker.m.ixdev.cn",
        "https://hub.rat.dev",
        "https://docker.xuanyuan.me"
    ]
}
EOF
# 指定镜像源
sudo systemctl daemon-reload
sudo systemctl restart docker
# 重载重启后生效
docker info | grep https
# 验证
docker pull hello-world
# 拉取镜像验证

PS： 或者参考 https://songxwn.com/cf-works-DockerHub-Proxy/ 自行搭建

MCP项目地址：

1
https://github.com/netboxlabs/netbox-mcp-server

一、部署架构

整体关系是：

1
2
3
4
5
AI 客户端 / Agent
        ↓ MCP
netbox-mcp-server
        ↓ NetBox REST API
NetBox

也就是说，netbox-mcp-server 本身不存储 NetBox 数据，它只是一个 MCP 适配层，后面仍然通过 NetBox REST API 查询数据。

二、准备条件

你需要提前准备好：

  1. 一台已经运行的 NetBox
  2. NetBox API Token
  3. Docker
  4. Docker Compose

假设你的 NetBox 地址是：

1
https://netbox.example.com

API Token 类似：

1
0123456789abcdef0123456789abcdef01234567

建议使用 只读权限 Token，除非你明确需要让 AI 修改 NetBox 数据。(注意目前只支持v1 的API Token)

三、创建部署目录

1
2
mkdir -p /opt/netbox-mcp-server
cd /opt/netbox-mcp-server

四、创建 .env 文件

  • .env文件会默认隐藏，打开修改直接输入全名即可。
1
2
3
4
5
6
7
8
cat > .env << 'EOF'
NETBOX_URL=https://netbox.example.com
NETBOX_TOKEN=your_netbox_api_token_here

# MCP Server 监听地址
MCP_HOST=0.0.0.0
MCP_PORT=8000
EOF

修改成你自己的 NetBox 地址和 Token：

1
vim .env

例如：

1
2
3
4
5
NETBOX_URL=https://netbox.songxwn.com
NETBOX_TOKEN=0123456789abcdef0123456789abcdef01234567

MCP_HOST=0.0.0.0
MCP_PORT=8000
  • 注意这里的监听端口是容器对外映射的端口

五、创建 docker-compose.yml 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
cat > docker-compose.yml << 'EOF'
services:
  netbox-mcp-server:
    image: netboxlabs/netbox-mcp-server:latest
    container_name: netbox-mcp-server
    restart: unless-stopped

    env_file:
      - .env

    environment:
      NETBOX_URL: ${NETBOX_URL}
      NETBOX_TOKEN: ${NETBOX_TOKEN}

    ports:
      - "${MCP_PORT:-8000}:8000"

    command:
      - "netbox-mcp-server"
      - "--host"
      - "0.0.0.0"
      - "--port"
      - "8000"
EOF

六、启动服务

1
docker compose up -d

查看容器状态：

1
docker compose ps

查看日志：

1
docker compose logs -f

如果启动成功，通常你会看到类似信息：

1
netbox-mcp-server listening on 0.0.0.0:8000

七、确认 MCP Server 是否运行

查看端口监听：

1
docker compose ps

或者：

1
curl http://127.0.0.1:8000

如果该 MCP Server 使用 SSE 或 Streamable HTTP，常见访问地址可能类似：

1
http://127.0.0.1:8000/sse

或者：

1
http://127.0.0.1:8000/mcp

具体 endpoint 需要以项目 README 或启动日志为准。

你也可以进入容器查看帮助：

1
docker compose exec netbox-mcp-server netbox-mcp-server --help

如果命令名不是 netbox-mcp-server，可以查看容器内可执行文件：

1
docker compose exec netbox-mcp-server sh

然后执行：

1
which netbox-mcp-server

或：

1
ls /usr/local/bin

八、连接 MCP 客户端

不同客户端的 MCP 配置略有不同。

方式一：HTTP / SSE 方式

如果你的 AI 客户端支持远程 MCP Server，可以配置类似：

1
2
3
4
5
6
7
{
  "mcpServers": {
    "netbox": {
      "url": "http://your-server-ip:8000/sse"
    }
  }
}

或者：

1
2
3
4
5
6
7
{
  "mcpServers": {
    "netbox": {
      "url": "http://your-server-ip:8000/mcp"
    }
  }
}

具体用 /sse 还是 /mcp，要看 netbox-mcp-server 当前版本支持的 transport。

方式二：Claude Desktop 本地 stdio 方式

如果你的 MCP 客户端只支持 stdio，例如部分 Claude Desktop 场景，可以不用长期暴露端口，而是让客户端直接通过 Docker 启动容器。

示例配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "mcpServers": {
    "netbox": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env",
        "NETBOX_URL=https://netbox.example.com",
        "--env",
        "NETBOX_TOKEN=your_netbox_api_token_here",
        "ghcr.io/netboxlabs/netbox-mcp-server:latest"
      ]
    }
  }
}

这种方式和 docker-compose up -d 的服务端模式不太一样：

  • docker-compose up -d 更适合 HTTP / SSE MCP Server；
  • docker run -i 更适合 stdio MCP Server。

⑨、如果 NetBox 运行在宿主机上

如果你的 NetBox 是直接跑在 Docker 宿主机上，例如：

1
http://127.0.0.1:8000

容器内部访问 127.0.0.1 指的是容器自己，不是宿主机。

这时 .env 不要写：

1
NETBOX_URL=http://127.0.0.1:8000

可以改成：

1
NETBOX_URL=http://host.docker.internal:8000

同时在 docker-compose.yml 中加入：

1
2
extra_hosts:
  - "host.docker.internal:host-gateway"

完整示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
services:
  netbox-mcp-server:
    image: ghcr.io/netboxlabs/netbox-mcp-server:latest
    container_name: netbox-mcp-server
    restart: unless-stopped

    env_file:
      - .env

    environment:
      NETBOX_URL: ${NETBOX_URL}
      NETBOX_TOKEN: ${NETBOX_TOKEN}

    extra_hosts:
      - "host.docker.internal:host-gateway"

    ports:
      - "${MCP_PORT:-8000}:8000"

    command:
      - "netbox-mcp-server"
      - "--host"
      - "0.0.0.0"
      - "--port"
      - "8000"

十、生产环境建议

如果你要在生产环境使用，建议不要直接裸露 8000 端口到公网。

推荐架构：

1
2
3
4
5
6
7
AI Client
   ↓ HTTPS
Nginx / Caddy / Traefik
   ↓
netbox-mcp-server
   ↓
NetBox API

建议至少做：

  1. HTTPS
  2. IP 白名单
  3. Basic Auth 或 OAuth 认证
  4. 使用只读 NetBox Token
  5. 限制 MCP Server 能访问的 NetBox 权限
  6. 日志审计
  7. 不要把 Token 写进 Git 仓库

十一、常见问题

1. 容器启动后立即退出

查看日志：

1
docker compose logs netbox-mcp-server

常见原因：

  • 命令名不对；
  • 参数不对；
  • 环境变量缺失；
  • NetBox 地址不可达；
  • Token 无效。

可以查看帮助：

1
docker compose run --rm netbox-mcp-server netbox-mcp-server --help

2. 连接 NetBox 失败

进入容器测试：

1
docker compose exec netbox-mcp-server sh

然后：

1
curl -H "Authorization: Token $NETBOX_TOKEN" "$NETBOX_URL/api/status/"

如果正常，应该能看到 NetBox API 返回。

3. 401 Unauthorized

说明 Token 不正确或权限不足。

检查：

1
echo $NETBOX_TOKEN

以及 NetBox 后台的 Token 是否有效。

4. HTTPS 证书问题

如果 NetBox 使用自签名证书，容器可能会报证书验证失败。

生产环境建议给 NetBox 配置正式证书。

临时测试可以考虑使用 HTTP，或者把内部 CA 证书挂载进容器。

十二、最小可用版本文件一览

最小文件结构：

1
2
3
/opt/netbox-mcp-server/
├── docker-compose.yml
└── .env

.env：

1
2
3
NETBOX_URL=https://netbox.example.com
NETBOX_TOKEN=your_netbox_api_token_here
MCP_PORT=8000

docker-compose.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
services:
  netbox-mcp-server:
    image: ghcr.io/netboxlabs/netbox-mcp-server:latest
    container_name: netbox-mcp-server
    restart: unless-stopped

    env_file:
      - .env

    ports:
      - "${MCP_PORT:-8000}:8000"

    command:
      - "netbox-mcp-server"
      - "--host"
      - "0.0.0.0"
      - "--port"
      - "8000"

启动：

1
docker compose up -d

查看日志：

1
docker compose logs -f

PS：之后会用此MCP，做一个AI Chat工具用于自然语言查询NetBox数据。

技术交流群

发送邮件到 ➡️ [email protected]

或者关注WX公众号：网工格物

微信扫码

博客（最先更新）

https://songxwn.com/