netbox-mcp-server

一个 Model Context Protocol 服务器，让 AI 助手能够读取——如果其 token 允许，也能写入——你的 NetBox 实例：DCIM、IPAM、电路、虚拟化、租户、电源，以及该实例已安装的所有插件。

它基于官方 @modelcontextprotocol/sdk，用 TypeScript 编写。作为支持 MCP 的客户端（Claude Desktop、Claude Code、Cursor、Codex）的子进程，在本地通过 stdio 运行。

只有五个工具，而不是几百个。 对象类型、字段、过滤器和枚举值都不是硬编码的——它们是在运行时从所连接实例自己的 /api/schema/ 文档派生出来的，因此这个工具面描述的是你的 NetBox，包括它的插件和自定义字段。tools/list 响应大约是 12,000 个字符的描述和 schema，约 3,000 个 token。

正在安装本工具？把这个粘贴到 Claude、ChatGPT 或任何可以浏览网页并运行命令的助手里：

读取 https://raw.githubusercontent.com/zenixsolutions/netbox-mcp-server/main/AGENTS.md 并按照其中的说明在我的 Mac 上安装 NetBox MCP 服务。

AGENTS.md 是一份为 AI 助手编写的、可以不依赖猜测逐步执行的操作手册。人类可以直接使用下面的“快速开始”。

快速开始

不需要克隆或构建任何东西。你的 MCP 客户端会用 npx 启动服务器，npx 在首次使用时会获取已发布的包。

你需要：

• Node.js >= 20.11（node --version）。Node 18 已停止维护，不受支持。

• 一个 NetBox API token —— 请参考下方 创建 token。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。在已有的 mcpServers 对象中添加 netbox 条目；不要替换整个文件。

{
  "mcpServers": {
    "netbox": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@zenixsolutions/netbox-mcp"],
      "env": {
        "NETBOX_URL": "https://netbox.yourcompany.com",
        "NETBOX_TOKEN": "your-api-token"
      }
    }
  }
}

将 command -v npx 返回的绝对路径用作 command。Claude Desktop 是从 Finder 启动的，永远不会加载你的 shell 配置文件，因此裸写 "npx"——就像裸写 "node" 一样——经常会以 spawn npx ENOENT 失败。修改配置后，请完全退出 Claude Desktop（Cmd-Q）并重新打开。

Claude Code

read -rs NETBOX_TOKEN                       # paste the token; nothing is echoed
claude mcp add netbox \
  --env NETBOX_URL="https://netbox.yourcompany.com" \
  --env NETBOX_TOKEN="$NETBOX_TOKEN" \
  -- "$(command -v npx)" -y @zenixsolutions/netbox-mcp
unset NETBOX_TOKEN

不要把 token 放在 ~/.zshrc 或其他任何 shell 配置文件中。它只应该出现在客户端配置里，其他任何地方都不要放。

若你不希望工具在两次重启之间发生变化，请固定版本 —— "@zenixsolutions/netbox-mcp@0.2.0"。本项目目前还在 1.0.0 之前，工具表面的变化都记录在 CHANGELOG 中。其他客户端请查看 AGENTS.md。

然后对你的 AI 助手说：“使用 netbox 工具，列出前 5 个站点。”

创建 token

NetBox → 用户菜单 → API Tokens → 添加 Token。

• 除非助手需要修改基础设施记录，否则不要勾选 Write enabled。这是唯一的写权限控制方式（见 写权限）。

• 设置一个过期时间。

• 将 token 的对象权限限制在助手确实需要的范围内。

Related MCP server: NetBox MCP Server

同时安装技能

上面的快速安装流程安装的是工具。netbox-modeling 技能安装的是驱动这些工具所需的判断力——构建顺序、必填字段、废弃模型，以及在写入任何内容之前需要你确认的计划。

docs/installing-the-skill.md 是分平台的说明页，其中包含此服务器运行的三个位置对应的准确路径和配置块：

• Claude（Desktop、Code、Cowork）——两步合成一步： /plugin marketplace add ZenixSolutions/netbox-mcp-server 然后 /plugin install netbox-mcp@zenix-solutions。这个插件同时包含配置和技能，并会提示你输入 URL 和 token。

• ChatGPT 桌面版（作为一个 Codex 宿主）—— 配置文件位于 ~/.codex/config.toml，技能位于 ~/.agents/skills/。

• Grok Build（xAI 的本地 Agent）—— TOML 文件位于 ~/.grok/config.toml，技能位于 ~/.grok/skills/；它还会在零配置情况下读取上面的 Claude 插件。

该页面还说明了哪些会自动更新、哪些不会。简单来说：Claude 插件会在会话开始时自动更新；其他内容都不会。

这五个工具

变更的预期路径是 netbox_discover → netbox_descrithe → netbox_write。 netbox_global_search 是这个路径的快捷方式：查找一个具名对象只需要一次调用，而不是三次。当你已经知道类型——dcim.device、ipam.prefix——时，直接调用一次 netbox_read 即可。

对象类型的键是单数形式的 <application>.<model>。插件模型是 plugins.<plugin>.<model>，是不可猜测的，这正是 netbox_discover 的作用。

几个值得了解的行为：

• 错误的对象类型或字段名会在本地被拒绝，同时会列出相近的或不谋而合的过滤器名称。NetBox 本身对于它无法识别的查询参数会返回 200 并返回整个未过滤集合，所以服务会拒绝未知的字段而不是将其透传。

• netbox_write 在发送任何信息之前会用实例的 schema 校验 data。被拒绝时返回的描述与 netbox_dessdescription 会返回的方式相同。

• update 是部分写操作。 只有 data 中出现的字段会被更新。

• delete 要求 confirm 与对象当前的 display 值必须完全相等。 先读取对象本身，复制 display，再传回。NetBox 的对象删除会级联——删除一个 site 可能会一起删除其下面的 racks、devices 和 prefixes——而且无法撤销。

• netbox_read 和 netbox_global_search 默认返回 Markdown，按需可返回 JSON。列表默认每页 50 条（最大 1000），并返回 total、has_more 和 next_offset；任何超过 25,000 个字符的响应都会被截断，同时给出继续读取的 offset。

而分层会带来往返成本。 一个简单的、本来用一次 netbox_read 就能回答的读操作，被观察到可能需要四次调用；身份查找可能需要十倍甚至更多。这是测量得出的，不是猜测，而重写工具描述也不能解决这个问题——参见 docs/reference/eval-model-in-loop.md 和 docs/reference/eval-results.md。分层换来的是一个能装进上下文窗口的 tools/list。

这种设计的理由来自 RFC-003。

配置

三个环境变量，没有其他。

实例的 OpenAPI 文档会在首次连接时获取，并缓存在 $XDG_CACHE_HOME/netbox（或 ~/.cache/netbox）目录下的磁盘上，缓存键由 /api/status/ 返回的 NetBox 版本和已安装插件决定。升级 /升级到 /api/ 或添加插件会使缓存失效；缓存无法读取或写入都不是致命错误。

写权限

**写权限是由 NetBox token 控制的，而不是由这个服务器控制。**这里没有服务器端的只读开关，这是有意为之：一个用来隐藏写工具的环境变量只是建议，而一个未勾选 write_enabled 并配置好对象权限的 token 是由 NetBox 强制执行的，工具参数无法绕过。

任何不需要修改记录的人都应使用只读 token。如果写入被拒绝，NetBox 会返回 403，服务器的错误文本会指出可能的原因，包括 token 的 write_enabled 标志。

安全运行本服务器，包括启用写权限的 token 的 prompt injection 风险，见 SECURITY.md。

命令行接口

这个二进制通常由客户端启动，但它有四个用于验证安装的动词。如果你是从 clone 构建的，请用 node dist/index.js 替换 netbox-mcp。

--check 是为诊断配置问题准备的方法。--help 在读取任何配置之前就返回，因此无论你的凭据是正确的、错误的还是缺失的，它都会打出相同的输出——它永远显示不了配置错误。

# Is the configuration usable? Names the offending variable and exits 78 if not.
NETBOX_URL=https://netbox.corp.com NETBOX_TOKEN="$NETBOX_TOKEN" netbox-mcp --check
# -> ok: netbox-mcp-server v0.2.0 configured for https://netbox.corp.com

# Does the binary work at all? Needs no credentials and makes no network calls.
netbox-mcp --list-tools
# -> netbox_global_search / netbox_discover / netbox_describe / netbox_read / netbox_write
#    5 tools registered.        (on stderr)

# Do the credentials work against NetBox itself?
curl -sS -H "Authorization: Token $NETBOX_TOKEN" \
  "$NETBOX_URL/api/dcim/sites/?limit=1" | head -c 200

把 token 放在 shell 变量中，不要直接写在命令里：命令行会进 shell 历史，并在 ps 中显示给机器上的所有进程。

兼容性与限制

最可靠的说明是 docs/compatibility.md。简单来说：

• 已使用 NetBox 4.6.0 与 netbox_inventory 2.6.0 进行契约测试—— 435 项检查，0 个缺陷。 但那只是单个实例，是证据，而不胜任能保证的范围。不同 NetBox 版本的响应结构可能不同；请在你的 bug 报告中包括你的版本。兼容性文档说明了如何用只读 token 在你自己的实例上运行契约测试套件，以及该返回什么结果。

• 仅支持 stdio。 没有远程 HTTP 传输，因此只支持 HTTP 的客户端（ChatGPT connector、Grok connector）无法使用本工具。

• 有一个插件已验证过。其他插件从未尝试过。

• 已知限制——往返成本、device_id 参数名、不支持文件上传、不支持 GraphQL——都在该文档中列出，这里就不再重复。

从代码构建

为贡献者以及无法访问 npm registry 的机器准备：

git clone https://github.com/zenixsolutions/netbox-mcp-server.git
cd netbox-mcp-server
npm ci
npm run build
node dist/index.js --check     # exits 0 when NETBOX_URL and NETBOX_TOKEN are usable

在未导出 NETBOX_TOKEN 的 shell 中运行 npm ci：它会执行依赖树中每个包的安装脚本，而每个脚本都会继承你的环境变量。

然后使用与上述相同的客户端配置，将 command 设置为 command -v node 得到的绝对路径，将 args 设置为 dist/index.js 的绝对路径：

"netbox": {
  "command": "/opt/homebrew/bin/node",
  "args": ["/Users/YOU/netbox-mcp-server/dist/index.js"],
  "env": { "NETBOX_URL": "...", "NETBOX_TOKEN": "..." }
}

MCP 客户端不会展开波浪号（~）——两个路径都必须是绝对路径。

故障排查

最常见的失败原因：在 GUI 客户端中出现 spawn npx ENOENT / spawn node ENOENT。 Claude Desktop 是从 Finder 启动的，永远不会加载你的 ~/.zshrc，因此由 nvm/fnm/asdf/Volta/Homebrew 安装的 npx 或 node 对它不可见。请在配置中填入 command -v npx（或 command -v node）得到的绝对路径，而不是裸字符串 "npx"。

第二常见的原因：Missing required environment variable ...。使用配置中设置的环境变量运行 --check —— 它会指出缺失的变量名并以退出码 78 结束。

Claude Desktop 会分别记录每个服务器的日志：

tail -f ~/Library/Logs/Claude/mcp-server-netbox.log

完整的症状与修复对照表：AGENTS.md。

开发

npm run dev           # tsx watch src/index.ts
npm run build         # tsc -> dist/
npm run typecheck     # tsc --noEmit, sources + tests
npm run lint          # eslint
npm run format:check  # prettier --check
npm test              # vitest run
npm run test:contract # opt-in, against a live instance with a read-only token
npm run eval          # opt-in, evals/

src/
  index.ts            entry point; argv parsing (--help/--version/--check/--list-tools)
  server.ts           server construction and introspection
  config.ts           env parsing / validation
  constants.ts        character limits, page sizes, env var names
  client.ts           axios-based NetBox client
  errors.ts           NetBox API error formatting
  formatting.ts       markdown rendering + pagination payload
  schema/             fetch, cache and interpret the instance's /api/schema/
  schemas/common.ts   shared Zod schemas
  tools/layered/      the five tools: search, discover, describe, read, write
skills/
  netbox-modeling/    agent skill, versioned with the tool contract it names
scripts/
  check-changelog.mjs release guard: CHANGELOG has a section for the current version

每个工具的描述文本都位于其实现旁边的 src/tools/layered/*.ts 中——该文本是大多数模型实际看到的接口，并且会以此标准进行审查。

贡献

欢迎提交 Issue 和 Pull Request——参见 CONTRIBUTING.md。

安全漏洞应私下报告，而不是作为公开 Issue 提交。参见 SECURITY.md。

免责声明

这是一个独立的、由社区维护的项目。它与 NetBox Labs 或 NetBox 开源项目无关联、未经其认可，也不受其支持。"NetBox" 是其各自所有者的商标。

按 MIT 许可证原样提供。你需要对自己授予 AI 助手的凭据所造成的一切后果负责——在为生产环境的 NetBox 实例签发具有写入权限的令牌之前，请先阅读 SECURITY.md。

许可证

MIT——参见 LICENSE。