netboxlabs-platform-mcp

NetBox Labs Platform MCP 服务

Platform MCP 服务是一个托管的 Model Context Protocol 服务（运行于 NetBox Cloud），通过 MCP 工具界面接入 NetBox 实例，让 Agent 能够读取和修改 NetBox 数据。它与开源的 netboxlabs/netbox-mcp-server（v1.2.2，2026-10-08——仅更新依赖项和安全修复；1.2.1 为 HTTP 传输添加了可选的 bearer-token 身份验证；拒绝 __in 查询，改用列表值——与下文规则相同）不同：平台服务提供 Code Mode、按用户进行身份验证、动态检测插件和模型，以及第一方产品集成（Assurance、Discovery）。

关于此服务的知识可能已过时。 该服务处于 Public Preview 阶段；工具清单、辅助函数签名和可用命名空间均会按部署情况实时生成并持续变化。执行操作前，务必先发现实际可用的接口（搜索架构／工具列表）——切勿假设某种对象类型、端点或辅助函数存在。

检索来源

来源	URL / 方法	用途
Platform MCP 文档	https://netboxlabs.com/docs/platform-mcp/	设置、客户端配置、身份验证、模式、连接选项
社区 MCP 服务	https://github.com/netboxlabs/netbox-mcp-server	开源只读替代方案
实时服务	已连接的 MCP 服务本身	权威的工具列表和 netbox_search_schema 是事实依据

连接与身份验证

• 端点： https://<instance>.cloud.netboxapp.com/mcp
• 传输方式： 基于 streamable HTTP 的 MCP（不使用 stdio——这是联网托管服务，而非本地子进程）。
• 身份验证： Authorization: Bearer nbt_<token>——一个 NetBox v2 API token（前缀为 nbt_，适用于 NetBox 4.5+）。启用按用户身份验证后，每次调用都会应用你自己的 token 所对应的 NetBox RBAC 权限。
• 连接选项（端点 URL 上的查询参数，严格使用小写）：?mode=discrete|code|both 用于选择该连接的工具界面（所有套餐均支持 discrete；code／both 需要支持 Code Mode 的套餐）；?read_only=true 会将任何套餐上的连接限制为仅可查询。省略这两个参数则使用套餐默认值；如果请求套餐不支持的选项，连接会失败并返回 HTTP 400。NetBox Labs 支持团队可将实例锁定为只读（此时会拒绝 read_only=false）。
• 客户可通过 NetBox Labs 支持团队在自己的实例上启用该服务。

任何支持基于 streamable HTTP 的 MCP 客户端都可使用（Claude Code/Desktop、Cursor、VS Code、ChatGPT Developer Mode）。文档页面提供可直接复制粘贴的客户端配置。

首先：确定所用模式

服务以三种模式之一公开工具；查看工具列表即可判断当前使用的模式：

• Code Mode——你会看到恰好 三个工具：netbox_search_schema、netbox_execute、rediscover_netbox。更高级的套餐默认使用此模式。这是主要且最高效的工具界面。
• Discrete Mode——你会看到约 34 个 netbox_* 工具（以及插件／产品工具）。每项操作各自对应一个工具。
• Both——上述工具全部可用。

如果看到 netbox_execute，请使用 Code Mode。如果只看到离散的 netbox_* 工具，请跳转到 Discrete Mode。

---

Code Mode

Code Mode 不再提供数十个离散工具（每个工具都需要单独往返调用，且会占用大量上下文），而是公开三个参数为 Python 代码 的工具。你可以编写一段简短程序，调用注入的 NetBox 辅助函数，在进程内完成筛选、联接和循环，并返回单个 result。这样就能将多次工具往返调用合并为一次。

三个工具

工具	参数	作用
netbox_search_schema(code)	Python 代码读取预加载的 schema 变量，并赋值给 result	发现。 在内存中的 schema 字典里进行本地筛选，不会与 NetBox 通信。执行操作前，先确认对象类型、端点和筛选条件。
netbox_execute(code)	Python 代码调用注入的辅助函数，并赋值给 result	主力工具。 对 NetBox 运行程序并返回 result。其描述会实时生成，列出此部署中可用的确切辅助函数。
rediscover_netbox()	无	仅用于恢复。 重新探测 NetBox，并协调工具清单和 schema。谨慎使用——见下文。

黄金循环（尽量减少往返次数）

1. 先搜索 schema，别猜。 调用 netbox_search_schema 确认正确的对象类型、筛选字段或特殊端点。猜测对象类型或路径是最常见的失败原因。
2. 编写一个 netbox_execute 程序来完成整个任务——在单个程序中获取数据、筛选、联接、循环和计算。不要针对每个对象调用一次 netbox_execute；如果可以用循环或单次列表调用，就应采用这种方式。
3. 务必赋值给 result。 如果没有赋值，就会收到“代码运行成功，但未赋值给 result”——白白浪费一次调用。
4. 读取时使用 fields=[...] 投影字段，以缩小负载（并降低结果大小上限的影响）。
5. 优先使用具名辅助函数，而不是原始 api()——它们带有验证功能，错误信息也更清晰。

# netbox_search_schema — confirm the type/filters first
result = {k: v for k, v in schema['object_types'].items() if v['app'] == 'dcim'}

# netbox_execute — do the whole task in one program
sites = get('dcim.site', filters={'name': 'NYC-DC1'}, fields=['id', 'name'])
site_id = sites['results'][0]['id']
devs = get('dcim.device', filters={'site_id': site_id, 'status': 'active'},
           fields=['id', 'name', 'role', 'primary_ip4'], limit=1000)
result = {'site': 'NYC-DC1', 'count': devs['count'], 'devices': devs['results']}

沙箱约定（代码允许执行的操作）

netbox_execute / netbox_search_schema 通过经过验证的沙箱运行。请遵守以下规则，否则代码会被拒绝：

• 禁止使用 import / from ... import。 这是最常见的失败原因——Agent 会尝试使用 json、re、ipaddress、math、collections。所需内容都已存在于命名空间或允许的内置函数中。 切勿编写 import。
• 禁止定义类、使用 del、async / await / yield。
• 禁止使用双下划线方法或内省功能（eval、exec、open、getattr、globals、__class__、__subclasses__ 等均会被拦截）。
• 仅允许使用内置函数——常见的包括：len、str、int、float、bool、list、dict、set、tuple、range、enumerate、zip、sorted、sum、min、max、any、all、abs、round、map、filter。
• 循环次数、运行时间和结果大小均有限制——请确保程序有界；投影字段以控制结果不超过上限。
• 必须赋值给 result。
• HTTP 错误会显示 NetBox 响应正文，包括逐字段验证错误——因此，失败的 create() / update() 会返回可供修正的详细信息，你可以据此在下一个程序中修正并重试。

注入的辅助函数

确切的辅助函数集合会实时显示在 netbox_execute 描述中，并根据能力（写入/IPAM 分配/GraphQL/脚本/插件/产品）进行限制。对象类型使用点号表示法（'dcim.device'）；路径形式（'dcim/devices'）也可解析。完整目录见 references/code-mode-helpers.md——需要特定签名时再加载。核心辅助函数如下：

get(type, filters={}, fields=[], limit=50, offset=0, ordering=None) → {count, next, previous, results[]}
get_by_id(type, id, fields=[]) → object
search(query, object_types=[], limit=5) → {type: [results]}
options(type) → field schema (required fields, choices)
discover_models(app=None) / inspect_model(app, endpoint)        # enumerate types incl. plugins
create(type, data) / update(type, id, data) / delete(type, id)  # WRITE-gated
bulk_create / bulk_update / bulk_delete                          # WRITE-gated
available_prefixes / available_ips / allocate_prefix / allocate_ip ...   # IPAM-gated
graphql(query, variables=None, analyze=True)                     # GRAPHQL-gated
api(method, endpoint, params=None, data=None)                    # raw escape hatch

筛选规则（两个容易踩的坑）

1. 切勿使用 __in。 在许多字段上，NetBox 会静默忽略 field__in 并返回所有行——结果看似可靠，实际完全错误。辅助函数会拒绝此用法。请将列表作为字段值传入：

   # WRONG
   get('dcim.site', filters={'id__in': [1, 2, 3]})
   # RIGHT — list value sends repeated query params, which NetBox honors
   get('dcim.site', filters={'id': [1, 2, 3]})
   

2. 不支持多级关联遍历。 类似 device__site_id 的嵌套筛选会被拒绝。请分两步查询——先获取父对象的 ID，再筛选子对象：

   racks = get('dcim.rack', filters={'site': 'nyc-dc1'}, fields=['id'])
   rack_ids = [r['id'] for r in racks['results']]
   devices = get('dcim.device', filters={'rack_id': rack_ids}, fields=['id', 'name'])
   result = devices['results']
   

NetBox 版本中的易踩坑点（辅助函数会原样传递 NetBox 的表示形式）

• 选择型自定义字段 — 在 NetBox 4.7+ 中，obj['custom_fields']['env'] 的值为 {'value': 'prod', 'label': 'Production'}（多选时为此类对象组成的列表）；在 4.5–4.6 中则为原始值。为兼容不同版本，请使用 v['value'] if isinstance(v, dict) else v 进行比较，并始终写入原始值（update('dcim.device', id, {'custom_fields': {'env': 'prod'}})）。
• config_context — 在 4.5–4.6 中，它会按对象渲染；在 4.7.0–4.7.2 中，它会被缓存且始终加载（所有 4.7.x 版本都会忽略 exclude）；在 4.7.3+ 中，将其排除在字段集之外即可再次跳过数据库操作。无论哪种情况，解决方法都是使用 fields=[...]——绝不要拉取完整的设备行。
• 服务 — 4.7+ 使用 port_mappings（['tcp/443', 'udp/53']）；protocol/ports 已弃用（仅对单协议服务填充，并将在 5.0 中移除）。请使用 {'port': 443} / {'protocol': 'tcp'} 进行筛选，而不要使用 protocol__ic。
• 批量写入 — 4.7+ 在 bulk_create/bulk_update 失败时会返回每个对象的错误（errors[].index = 对象在列表中的位置，更新时的 errors[].id = 对象 ID）；但批次仍会全部成功或全部失败，因此请修正这些条目后重新提交。4.5–4.6 只会报告第一个错误。完整详情请见：netbox-api-integration。

何时使用 rediscover_netbox()

仅当你有明确理由认为工具清单已过时才使用：用户刚安装或卸载了插件；你确实预期存在的工具返回“tool not found”；或者你不再预期存在的工具仍在公告中。插件注册失败后，也可通过此方法恢复。请勿在每次操作前调用它来“刷新”NetBox 数据（辅助函数始终读取最新数据），也不要在会话开始时“以防万一”调用——每次调用都会产生一次往返通信，并重新注册工具。

更多端到端程序请见 references/code-mode-workflows.md。

---

离散模式

Code Mode 不可用时，每项操作都是一个独立的 MCP 工具，具有类型化签名和详细的文档字符串。离散模式会直接提供更多上下文（工具列表和文档字符串就在你面前），因此需要探索的内容更少——但每项操作都需要单独往返通信。核心工具：

分组	工具
读取	netbox_get_objects、netbox_get_object_by_id、netbox_search_objects、netbox_get_changelogs
写入	netbox_create_object、netbox_update_object、netbox_delete_object、netbox_bulk_create_objects、netbox_bulk_update_objects、netbox_bulk_delete_objects
连通性	netbox_trace_cable、netbox_get_cable_paths、netbox_get_rack_elevation、netbox_get_connected_device
IPAM	netbox_get_available_*（前缀/IP/VLAN/ASN）、netbox_allocate_next_*
自动化/内省	netbox_render_config、netbox_run_script、netbox_graphql_query、netbox_get_object_schema、discover_models、inspect_model、rediscover_netbox

离散模式的文档字符串已明确规定以下规则（请遵循）：

• 始终传入 fields=，以尽量减少令牌用量（读取时可减少 80–90% 的载荷）。limit 默认值为 50，最大值为 1000。
• __in 和多跳规则与代码模式相同——传入列表值；使用两步模式。
• netbox_get_changelogs：action 必须使用祈使式单数（"create"/"update"/"delete"——NetBox 会对 "updated" 返回 400 错误）。changed_object_type 的格式为 "app.model"；changed_object_type_id 是整数 ContentType 主键。
• 对象类型既接受 "dcim.device"，也接受 "dcim/devices"。使用 discover_models() 枚举类型（包括插件）。

产品与插件命名空间

当租户拥有相应权限且集成已配置时，会显示其他辅助工具/工具：

• 插件： 分支（branch_*）、变更（change_request_*、reviews、comments）、自定义对象（custom_type_*/custom_object_*）。
• 产品： Assurance（assurance_*）和 Discovery（discovery_*）。

这些功能均受权限控制——只有租户拥有相应产品/插件时才会出现。不要假定它们存在；请先发现它们。有关其领域逻辑，请参阅 netbox-branching、netbox-changes、netbox-custom-objects、netbox-assurance 和 netbox-discovery。

反模式

1. 在代码模式下编写 import → “Forbidden operation: Import.” 这是最常见的失败。只能使用命名空间辅助工具和允许的内置项。
2. 未先搜索架构 → 猜错对象类型或使用不受支持的筛选条件。执行前通过 netbox_search_schema 确认。
3. __in 陷阱 → 结果范围被悄然扩大或请求被拒绝。将列表用作字段值。
4. 多跳筛选 → 请求被拒绝。使用两步模式。
5. 忘记赋值给 result → 浪费一次轮次。
6. 每个对象调用一次 netbox_execute，而不是使用单个循环/批量程序 → 违背代码模式的初衷。
7. 将 rediscover_netbox 当作预防措施而过度调用 → 这会产生往返开销，并不会刷新数据。
8. 不投影 fields= → 负载过大、触及结果上限、浪费令牌（两种模式均如此）。
9. 假定产品/插件命名空间存在 → 它受权限控制。请先发现它。
10. 未定义名称（ip_network、re 等）导致 NameError → 只有注入的辅助工具和允许的内置项可用。

版本说明

NetBox 4.7（2026-09-02）

• 根据文档，服务端自身的工具名称、模式和身份验证均未改变。改变的是辅助工具返回的 NetBox 数据：选择型自定义字段返回 {value, label}、默认包含 config_context（在 4.7.3+ 中使用 ?omit=config_context 可省略）、服务上的 port_mappings、以及逐对象的批量错误——详见 NetBox 版本陷阱。
• ?background=true（202 + job）是批量写入时的原始 REST 选项；文档中的批量辅助工具均为同步操作。只能通过 api() 逃生口传入（params={'background': 'true'}），并在后续程序中轮询任务（core.job）——请先通过 netbox_search_schema 确认是否支持，并且绝不要以这种方式创建 API 令牌（自 4.7.2 起会被拒绝）。
• 插件命名空间（分支、变更、自定义对象）需要使用支持 NetBox 4.7 的插件版本——例如 netbox-branching 1.2.x 仅支持 4.7（1.1.x 适用于 4.4–4.6）。版本系列： netbox-branching、netbox-changes、netbox-custom-objects。

参考资料

• references/code-mode-helpers.md — 完整的注入式辅助工具目录，包含签名并按能力门控分组。需要准确签名时加载。
• references/code-mode-workflows.md — 端到端的单程序示例（读取、ID 列表、两步联接、IPAM 分配、变更日志审计）。