前言：为什么要用 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

Docker 单命令部署

1
2
3
4
5
6
7
8
docker run --rm \
  -e NETBOX_URL=https://demo.netbox.dev \
  -e NETBOX_TOKEN=ayydoR3uYF8WWa1Cx9wmt8K4CdJRh3OoMOFcnDY9 \
  -e TRANSPORT=http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -p 8000:8000 \
  netboxlabs/netbox-mcp-server:latest

PS： -e MCP_AUTH_TOKEN=ayydoR3uaaCx9wmtc8K4CdJRh3OoMOFcDY9 \ 可加认证密钥

Docker Compose 持久化部署

部署架构

整体关系是：

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

创建 docker-compose.yml 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
cat > docker-compose.yml << 'EOF'
services:
  netbox-mcp-server:
    image: netboxlabs/netbox-mcp-server:latest
    container_name: netbox-mcp-server
    restart: unless-stopped
    environment:
      NETBOX_URL: https://netbox.example.com/
      NETBOX_TOKEN: <your-api-token>
      TRANSPORT: http
      HOST: 0.0.0.0
      PORT: "8000"
      # MCP_AUTH_TOKEN: <a-strong-random-token>

    ports:
      - "8000:8000"
EOF

PS：MCP_AUTH_TOKEN 默认注释方便学习调试

生成API密钥

1
2
openssl rand -hex 32

启动服务

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"

技术交流群

发送邮件到 ➡️ [email protected]

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

微信扫码

博客（最先更新）

https://songxwn.com/