NetBox MCP

NetBox MCP 服务是一个基于 Python 的模型上下文协议（MCP）服务，可让 AI 助手结构化地访问 NetBox——网络基础设施（DCIM 和 IPAM）的事实来源。一组精简的通用工具涵盖 NetBox 4.7 的全部 139 种核心对象类型（以及启用时的插件类型），另有用于搜索、变更日志、GraphQL、空闲 IP/前缀/VLAN 分配、电缆路径追踪、配置渲染以及（可选）netbox-branching 的专用工具。写入操作可以完全隐藏（只读模式），也可以模拟执行（试运行模式）。

✨ 功能

核心功能

• 通过一个工具查询任意 NetBox 对象类型，支持筛选、排序和分页
• 使用 fields、omit 和 brief 缩小响应内容——这些工具会引导模型使用它们
• 同时搜索多种对象类型，并明确报告搜索失败或结果被截断的类型
• 读取变更日志（谁在何时更改了什么）以及 NetBox 状态、版本和插件信息
• 以一次往返执行只读 GraphQL 查询，获取嵌套数据
• 列出空闲 IP、前缀、VLAN 和 ASN；追踪电缆路径；渲染设备配置

管理操作

• 创建、更新和删除任意对象类型，支持单个或批量操作（NetBox 会将批量写入作为一个事务执行）
• 原子地分配下一个空闲 IP、前缀、VLAN 或 ASN
• 可选择将变更暂存到 netbox-branching 分支，而非 main
• 写入前查看对象类型的可写字段和可选值

高级功能

• 只读模式会隐藏所有写入工具；试运行模式会将所有写入操作转换为预览
• 支持 NetBox v2（Bearer nbt_...）和旧版 v1（Token ...）API 令牌
• 发现插件对象类型（例如 netbox_dns.zone）
• 验证筛选条件，拒绝 NetBox 会静默忽略的筛选条件（__in、多跳查找）
• 遇到 429/5xx 错误时重试，但服务器出错后绝不重放创建操作
• 基于标签的工具筛选、可选的工具搜索转换、速率限制和响应大小限制
• HTTP 传输支持 Bearer 令牌身份验证
• 提供多种传输选项（STDIO、SSE、HTTP）
• 可选集成 Sentry 进行错误跟踪

🚀 安装

先决条件

• Python 3.11 至 3.15
• NetBox 实例，版本为 4.2 或更高版本。较新版本添加的功能（omit、v2 令牌、/api/authentication-check/）会在服务检测到后使用
• 具有所需助手权限的 NetBox API 令牌。令牌才是真正的安全边界：只读令牌无法执行写入操作，无论本服务的设置如何

从 PyPI 快速安装

最简单的入门方式是从 PyPI 安装：

# Using UV (recommended)
uvx netbox-mcp

# Or using pip
pip install netbox-mcp

运行服务前，请记得为 NetBox 实例配置环境变量：

# Create environment configuration
export NETBOX_URL=https://netbox.example.com
export NETBOX_TOKEN=nbt_your-key.your-token

从源代码安装

1. 克隆仓库：

git clone https://github.com/mhajder/netbox-mcp.git
cd netbox-mcp

2. 安装依赖：

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

3. 配置环境变量：

cp .env.example .env
# Edit .env with your NetBox URL and API token

4. 运行服务：

# Using UV (recommended)
uv run netbox-mcp

# Or using the installed command directly
netbox-mcp

使用 Docker

GitHub Packages 上提供了 Docker 镜像，方便部署。

docker pull ghcr.io/mhajder/netbox-mcp:latest

开发环境设置

使用其他工具进行开发：

# Clone and install with development dependencies
git clone https://github.com/mhajder/netbox-mcp.git
cd netbox-mcp
uv sync --group dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/

# Run linting and formatting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run ty check .

# Setup prek hooks
uv run prek install

🔧 配置

环境变量

# NetBox MCP Server Environment Configuration

# NetBox Connection Details
NETBOX_URL=https://netbox.example.com

# API Token - v2 tokens (nbt_<key>.<token>, NetBox 4.5+) are sent as "Bearer",
# legacy v1 tokens as "Token"
NETBOX_TOKEN=nbt_your-key.your-token

# SSL Configuration
NETBOX_VERIFY_SSL=true
# Total time allowed for one NetBox request, retries included (seconds)
NETBOX_TIMEOUT=30

# Branching (requires the netbox-branching plugin)
# Set NETBOX_BRANCHING_ENABLED true to add the branch tools and the 'branch'
# argument to every tool. Off by default - leave it off on a NetBox without the plugin
NETBOX_BRANCHING_ENABLED=false
# Default branch (name or schema ID) used by every call; empty = main.
# Requires NETBOX_BRANCHING_ENABLED=true
NETBOX_BRANCH=

# Plugin Discovery
# Set NETBOX_PLUGIN_DISCOVERY true to expose plugin models (e.g. netbox_dns.zone)
NETBOX_PLUGIN_DISCOVERY=false

# Read-Only Mode
# Set READ_ONLY_MODE true to hide all write tools (create, update, delete)
READ_ONLY_MODE=false

# Dry-Run Mode
# Set DRY_RUN_MODE true to make every write tool only simulate the change:
# it returns the request it would send and never modifies NetBox
DRY_RUN_MODE=false

# Disabled Tags
# Comma-separated list of tags to disable tools for (empty by default)
# Example: DISABLED_TAGS=delete,graphql,branching
DISABLED_TAGS=

# Logging Configuration
LOG_LEVEL=INFO

# Response Size Limit
# Maximum tool response size in bytes; larger responses are truncated (empty = unlimited)
RESPONSE_MAX_SIZE=

# Rate Limiting
# Set RATE_LIMIT_ENABLED true to enable rate limiting
RATE_LIMIT_ENABLED=false
RATE_LIMIT_MAX_REQUESTS=60
RATE_LIMIT_WINDOW_MINUTES=1

# Tool Search Transform (Optional)
# Set TOOL_SEARCH_ENABLED true to replace full tool listings with search_tools + call_tool
TOOL_SEARCH_ENABLED=false
# Search strategy: bm25 (natural language) or regex (pattern match)
TOOL_SEARCH_STRATEGY=bm25
# Maximum number of tools returned by search_tools
TOOL_SEARCH_MAX_RESULTS=5

# Sentry Error Tracking (Optional)
# Set SENTRY_DSN to enable error tracking and performance monitoring
# SENTRY_DSN=https://[email protected]/6789
# Optional Sentry configuration
# SENTRY_TRACES_SAMPLE_RATE=1.0
# SENTRY_SEND_DEFAULT_PII=false
# SENTRY_ENVIRONMENT=production
# SENTRY_RELEASE=1.2.3
# SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
# SENTRY_PROFILE_LIFECYCLE=trace
# SENTRY_ENABLE_LOGS=true

# MCP Transport Configuration
# Transport type: 'stdio' (default), 'sse' (Server-Sent Events), or 'http' (HTTP Streamable)
# 'streamable-http' is accepted as an alias for 'http'. Any other value stops
# the server at startup.
# MCP_TRANSPORT=stdio

# HTTP Transport Settings (used when MCP_TRANSPORT=sse or MCP_TRANSPORT=http)
# Host to bind the HTTP server (default: 127.0.0.1)
# MCP_HTTP_HOST=127.0.0.1
# Port to bind the HTTP server (default: 8000)
# MCP_HTTP_PORT=8000
# Optional bearer token for authentication (leave empty for no auth)
# MCP_HTTP_BEARER_TOKEN=
# Set NETBOX_TOKEN_PASSTHROUGH true to make every client authenticate with its own
# NetBox API token (Authorization: Bearer <token>); NetBox then applies that user's
# permissions. NETBOX_TOKEN is ignored. Cannot be combined with MCP_HTTP_BEARER_TOKEN
# NETBOX_TOKEN_PASSTHROUGH=false

🧰 可用工具

对象类型的命名方式为 app.model，与 NetBox 本身的命名方式一致（dcim.device、ipam.prefix、virtualization.virtualmachine）。也接受 dcim/devices 这样的 API 路径。启用分支功能后，每个读取或写入对象的工具还会接受可选的 branch 参数。

对象（读取）

工具	描述
netbox_list_object_types	列出受支持的对象类型及其端点（核心类型和发现的插件类型）
netbox_get_objects	列出某类型的对象，可使用 filters、fields、omit、brief、ordering、limit、offset
netbox_get_object	按 ID 获取一个对象
netbox_search_objects	一次跨多个对象类型进行全文搜索（q）
netbox_describe_object_type	查看某类型的可写字段：数据类型、必填项、可选值
netbox_get_changelogs	更改日志条目，按时间从新到旧排列

专用工具（读取）

工具	描述
netbox_get_status	NetBox 版本、插件、工作进程、已认证用户和此服务的模式
netbox_graphql_query	只读 GraphQL 查询（不接受变更操作）
netbox_get_available	前缀或 IP 范围内的可用 IP／前缀、VLAN 组中的 VLAN、ASN 范围内的 ASN
netbox_trace_cable	从接口、前／后／控制台／电源端口或电路终端开始，追踪完整的线缆路径
netbox_render_config	根据配置模板渲染设备或 VM 的配置
netbox_list_branches	列出 netbox-branching 分支（仅在 NETBOX_BRANCHING_ENABLED=true 时可用）

写入

工具	描述
netbox_create_object	创建一个对象
netbox_update_object	部分更新一个对象（PATCH）
netbox_bulk_create_objects	在一个事务中创建最多 500 个对象
netbox_bulk_update_objects	在一个事务中更新最多 500 个对象
netbox_allocate_available	分配下一个可用的 IP、前缀、VLAN 或 ASN
netbox_create_branch	创建 netbox-branching 分支（仅在 NETBOX_BRANCHING_ENABLED=true 时可用）
netbox_delete_object	删除一个对象（destructiveHint）
netbox_bulk_delete_objects	在一个事务中删除最多 500 个对象（destructiveHint）

工具标签

每个工具都带有 netbox 标签以及一个分组标签，可通过 DISABLED_TAGS 关闭：objects、search、changelog、status、graphql、ipam、dcim、config、branching、write 和 delete。读取工具还带有 read-only 标签。

🔒 安全与防护功能

只读模式

只读模式会隐藏所有写入工具，客户端只能看到 11 个读取工具（启用分支功能时为 12 个）：

READ_ONLY_MODE=true

试运行模式

试运行模式会保留写入工具，但这些工具都不会更改 NetBox。每个工具都会解析并验证目标，然后返回本应发送的请求，并标记为 "dry_run": true。更新和删除操作也会获取当前对象，因此预览会显示将要更改的值，以及将被删除的确切内容：

DRY_RUN_MODE=true

READ_ONLY_MODE 优先级更高：同时设置两种模式时，写入工具会被隐藏。

NetBox 分支

借助 netbox-branching 插件，可以先在分支中暂存更改，并在合并到 main 之前进行审核。分支支持默认关闭，因此未安装该插件的 NetBox 不会提供分支工具，也不会有 branch 参数。可通过以下方式启用：

NETBOX_BRANCHING_ENABLED=true

这会添加 netbox_list_branches 和 netbox_create_branch，并为其他每个工具添加 branch 参数（分支名称或其架构 ID）。如需默认将每次调用都发送到同一分支：

NETBOX_BRANCH=assistant-changes

如果设置了 NETBOX_BRANCH，但没有设置 NETBOX_BRANCHING_ENABLED=true，则属于配置错误：服务会拒绝启动，而不会静默地将更改写入 main。

分支名称会解析为 X-NetBox-Branch 标头所需的架构 ID。合并、同步和还原操作不会作为工具公开——这些操作应由人工审核。

插件发现

NETBOX_PLUGIN_DISCOVERY=true

首次调用指定未知类型时（或运行 netbox_list_object_types 时），服务会读取 /api/core/object-types/，并添加所有带有 REST 端点的插件模型（例如 netbox_dns.zone）。插件类型不会覆盖核心类型。如果发现失败，核心类型仍可正常使用。

基于标签的工具筛选

设置禁用标签即可停用特定类别的工具。例如，允许创建和更新，但始终禁止删除：

DISABLED_TAGS=delete

响应大小限制

大型 NetBox 对象很快就会累积成大量数据。RESPONSE_MAX_SIZE 会截断任何超过指定字节数的工具响应：

RESPONSE_MAX_SIZE=200000

面向大型工具集的工具搜索

对于工具数量较多的服务，FastMCP 工具搜索可以缩减提示词大小。 启用后，list_tools 会返回两个合成工具：

• search_tools：查找匹配的工具并返回其完整架构
• call_tool：按名称执行任何已发现的工具

通过以下方式启用：

TOOL_SEARCH_ENABLED=true
TOOL_SEARCH_STRATEGY=bm25      # bm25 or regex
TOOL_SEARCH_MAX_RESULTS=8      # optional, default is 5

bm25 支持自然语言查询，而 regex 使用正则表达式 pattern 输入，以便进行确定性匹配。

工具搜索会遵循现有的可见性控制（只读模式和禁用标签）。

速率限制

服务支持速率限制，以控制 API 使用并防止滥用。启用后，会使用滑动窗口算法按客户端限制请求。

在 .env 文件中设置以下环境变量即可启用速率限制：

RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=60    # Maximum requests allowed per window (default: 60)
RATE_LIMIT_WINDOW_MINUTES=1   # Window size in minutes

如果将 RATE_LIMIT_ENABLED 设为 true，服务就会应用速率限制中间件。请根据环境需要调整 RATE_LIMIT_MAX_REQUESTS 和 RATE_LIMIT_WINDOW_MINUTES。

Sentry 错误跟踪与监控（可选）

服务可选支持 Sentry，用于错误跟踪、性能监控和调试。Sentry 集成为完全可选项，且仅在完成配置后才会初始化。

安装

如需启用 Sentry 监控，请安装可选依赖：

# Using UV (recommended)
uv sync --extra sentry

配置

在 .env 文件中设置 SENTRY_DSN 环境变量即可启用 Sentry：

# Required: Sentry DSN for your project
SENTRY_DSN=https://[email protected]/6789

# Optional: Performance monitoring sample rate (0.0-1.0, default: 1.0)
SENTRY_TRACES_SAMPLE_RATE=1.0

# Optional: Include personally identifiable information (default: false).
# When true, tool inputs and outputs (NetBox inventory data) are sent to Sentry.
SENTRY_SEND_DEFAULT_PII=false

# Optional: Environment name (e.g., "production", "staging")
SENTRY_ENVIRONMENT=production

# Optional: Release version (auto-detected from package if not set)
SENTRY_RELEASE=1.2.3

# Optional: Profiling - continuous profiling sample rate (0.0-1.0, default: 1.0)
SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0

# Optional: Profiling - lifecycle mode for profiling (default: "trace")
# Options: "all", "continuation", "trace"
SENTRY_PROFILE_LIFECYCLE=trace

# Optional: Enable log capture as breadcrumbs and events (default: true)
SENTRY_ENABLE_LOGS=true

功能

启用后，Sentry 会自动捕获：

• 异常与错误：所有未处理的异常及其完整上下文
• 性能指标：请求/响应时间和跟踪数据
• MCP 集成：详细的 MCP 服务活动和交互记录
• 日志与面包屑：用于调试的应用程序日志和事件轨迹
• 上下文数据：环境、客户端信息和请求参数

获取 Sentry DSN

1. 在 sentry.io 创建免费账户
2. 创建新的 Python 项目
3. 从项目设置中复制 DSN
4. 将其设置在 .env 文件中

禁用 Sentry

Sentry 完全是可选项。如果未设置 SENTRY_DSN，服务会正常运行，不会集成 Sentry，也不会收集任何监控数据。

SSL/TLS 配置

服务器支持 SSL 证书验证和自定义超时设置：

NETBOX_VERIFY_SSL=true    # Enable SSL certificate verification
NETBOX_TIMEOUT=30         # Total time per request, retries included (seconds)

证书会通过操作系统信任存储进行验证，因此只要操作系统信任内部 CA，位于该 CA 后面的 NetBox 就能正常工作。设置 SSL_CERT_FILE 或 SSL_CERT_DIR 时，它们的优先级更高。

传输配置

服务器支持多种 MCP 协议传输机制：

STDIO 传输（默认）

默认传输使用标准输入/输出进行通信。这非常适合本地使用，以及与通过 stdin/stdout 通信的工具集成：

MCP_TRANSPORT=stdio

HTTP SSE 传输（服务器发送事件）

对于基于网络的部署，可以使用 HTTP 和服务器发送事件。这样就能通过 HTTP 访问 MCP 服务并进行实时流式传输：

MCP_TRANSPORT=sse
MCP_HTTP_HOST=127.0.0.1        # Localhost
MCP_HTTP_PORT=8000           # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

通过 SSE 传输使用 bearer token 时，客户端必须在请求中包含该 token：

curl -H "Authorization: Bearer your-secret-token" http://localhost:8000/sse

HTTP Streamable 传输

HTTP Streamable 传输通过 HTTP 进行通信，并支持请求/响应流式传输。这非常适合 Web 集成以及需要 HTTP 端点的工具：

MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1        # Localhost
MCP_HTTP_PORT=8000           # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

通过 Streamable 传输使用 bearer token 时：

curl -H "Authorization: Bearer your-secret-token" \
     -H "Accept: application/json, text/event-stream" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
     http://localhost:8000/mcp

按用户使用 NetBox token

默认情况下，所有客户端共用服务器的 NETBOX_TOKEN，因此 NetBox 看到的只有一个用户。设置 NETBOX_TOKEN_PASSTHROUGH=true 后，每个客户端改为发送自己的 NetBox API token。NetBox 会应用该用户的权限，变更日志也会记录真实用户：

MCP_TRANSPORT=http
MCP_HTTP_HOST=0.0.0.0
NETBOX_TOKEN_PASSTHROUGH=true

claude mcp add --transport http netbox https://netbox-mcp.example.com/mcp \
  --header "Authorization: Bearer nbt_your-key.your-token"

• 未携带 token，或携带的 token 被 NetBox 拒绝时，请求会收到 HTTP 401。如果在 10 秒内（或 NETBOX_TIMEOUT 设置的更短时间内）无法联系 NetBox 验证 token，请求会收到带有 Retry-After 的 HTTP 503，客户端可以重试，而不必重新登录。如果 NetBox 返回了自己的 Retry-After，该 HTTP 503 会沿用此值。已接受的 token 会缓存 60 秒。此后最多 10 分钟内，token 仍会立即被接受，同时服务器在后台向 NetBox 重新验证，因此已知用户无需等待验证，即使 NetBox 中断也一样。重新验证结果返回后，被撤销的 token 会被移除；在此之前，它只能用于不调用 NetBox 的工具（例如工具列表），因为 NetBox 会拒绝每个实际调用中携带的该 token。被拒绝的 token 会缓存 30 秒，因此，如果在 NetBox 中创建 token 前就尝试使用，刚创建的 token 可能会被拒绝最多 30 秒。最多同时有 8 个 token 验证请求到达 NetBox；携带服务器尚未见过的 token 的请求会等待空闲名额，若等待时间超过验证超时，则会收到 HTTP 503。
• v2（nbt_...）和旧版 v1 token 均可使用；服务器会使用正确的方案将其发送给 NetBox。
• NETBOX_TOKEN 会被忽略。仅支持 http 和 sse 传输；如果同时设置了 MCP_HTTP_BEARER_TOKEN，服务器将拒绝启动，因为两者都使用 Authorization 标头。
• 设置 RATE_LIMIT_ENABLED=true 后，每个 NetBox 用户都有自己的速率限制窗口（NetBox 4.5 之前为每个 token 单独设置），因此该限制不再限定服务器对 NetBox 的总负载。
• 设置 NETBOX_PLUGIN_DISCOVERY=true 后，使用任意用户 token 找到的插件类型都会添加到一个共享列表中。rediscover 会将该列表替换为调用用户可见的插件类型，从而移除未安装的插件；如果另一位用户调用了只有其本人可见的类型，服务器会使用该用户的 token 重新发现插件。
• 客户端会将其 NetBox token 发送给此服务器，因此请将服务器部署在 HTTPS 后面。

注意：HTTP 传输要求使用正确的 JSON-RPC 格式，其中包含 jsonrpc 和 id 字段。某些操作可能还要求服务器先初始化会话。

健康检查端点

两种 HTTP 传输方式（sse 和 http）都提供 GET /health，在服务正常处理请求时返回 200 ok。该端点无需 bearer 令牌，也不会连接 NetBox，因此 NetBox 故障不会导致 MCP 服务被标记为不健康。 Docker 镜像的 HEALTHCHECK 使用此端点：

curl http://localhost:8000/health

有关 FastMCP 传输方式的更多信息，请参阅 FastMCP 文档。

🤝 贡献

欢迎贡献。开发环境设置、检查和提交消息格式请参阅 CONTRIBUTING.md，报告 Bug 和功能请求请使用问题模板。

发现安全问题？请按照 SECURITY.md 中的说明私下报告。

📜 许可证

MIT License - 详情请参阅 LICENSE。