UniFi Site Manager and Network (unofficial)

the-real-unifi-mcp

一个 MCP 服务，可通过官方云端点，让 Claude（或任何 MCP 客户端）完全读写 UniFi Site Manager 和 Network API。仅支持云端，使用 stdio 传输。

非官方项目。 此服务与 Ubiquiti Inc. 无关联，也未获其认可。UniFi 和 Ubiquiti 是 Ubiquiti Inc. 的商标，此处仅用于指明本软件所适配的 API；请参阅 NOTICE。

提供 UniFi Site Manager API 密钥后，MCP 客户端即可通过 169 个工具（涵盖文档所述的 API 功能）列出控制台、检查设备和客户端，并管理网络、WiFi、防火墙策略等。

功能

• 169 个工具，覆盖两个 UniFi API，支持读写操作。
• **三层工具设计：**86 个手动封装工具（10 个 Site Manager + 76 个 Network）+ 82 个自动生成工具（每个文档所述的端点各一个）+ 1 个原始请求应急工具（86 + 82 + 1 = 169）。工具契约由 tests/contract/tools-contract.json 固定。
• MCP 资源和MCP 提示词，提供现成的工作流。
• 延迟 ID 发现（consoleId / Network siteId / Site Manager siteId），并在进程生命周期内缓存。
• 默认启用写入保护：UNIFI_CONFIRM_WRITES（默认值为 true）会让破坏性工具先预览、再确认；设为 false 可直接执行写入操作。模型本身可以发送 confirm: "YES"，因此这只是增加了一步操作，并非人工审批（请参阅 SECURITY.md）。
• 服务器自身 stderr 日志行中的机密信息会被脱敏（已知密钥模式和按值匹配的已配置 API 密钥）。

要求

• Node.js 22.12 或更高的 22.x 版本、24.x 版本，或 26 及更高版本（engines：^22.12.0 || ^24.0.0 || >=26.0.0，与测试工具链 vitest 的版本范围一致）。不支持 Node 23 和 25。
• 具有 Network 权限范围的 UniFi Site Manager API 密钥。请在 unifi.ui.com 的 Settings → API 下创建。
• 固件版本 ≥ 5.0.3 的 UniFi Console（Network API 的要求）。

安装

从 npm 安装（推荐）

无需安装步骤：MCP 客户端会通过 npx 启动服务，并在首次使用时从 npm 获取软件包。

npx -y the-real-unifi-mcp   # starts the server on stdio; needs UNIFI_API_KEY in the environment

或者全局安装，并使用 the-real-unifi-mcp 命令：

npm install -g the-real-unifi-mcp

如果只想在更改配置时才接收更新，请固定版本（the-real-unifi-mcp@<version>）。从 v0.2.1 起的版本由 GitHub Actions 发布到 npm，并附带来源证明（v0.2.0 仅作为 GitHub 版本发布）；可通过 npm audit signatures 验证。

从源代码安装

git clone https://github.com/mguttmann/the-real-unifi-mcp.git
cd the-real-unifi-mcp
npm ci
cp .env.example .env
# Edit .env: set UNIFI_API_KEY (Site Manager key with Network scope)
npm run build   # prebuild runs lint, typecheck and unit tests first
npm start       # node dist/index.js; reads .env from the current directory

作为 MCPB 软件包安装

npm ci
npm run build:mcpb
# Writes release/the-real-unifi-mcp-<version>.mcpb (install it in Claude Desktop) and its SBOM.

此软件包会将设置（API 密钥、确认写入、只读、隐藏机密信息、日志级别）映射到下方的环境变量，并使用 ${user_config.<key>} 占位符。如果宿主启动服务时未替换这些占位符，仍为此类占位符的值将被视为未设置：每个开关都保持默认值，缺少密钥会导致服务停止，并发出指出相关变量的警告。

从 v0.2.0 起发布的版本会附带 .mcpb、npm tarball、CycloneDX SBOM 和 SHA256SUMS；请参阅 docs/RELEASING.md。

配置

变量	默认值	描述
UNIFI_API_KEY	（必填）	具有 Network 范围的 Site Manager API 密钥
UNIFI_API_BASE	https://api.ui.com	API 基础 URL。此主机会接收 API 密钥：除非要针对本地 stub 进行测试，否则请保留默认值。必须使用 https://（仅对 127.0.0.1、[::1] 或 localhost 允许使用纯 http://），并且必须是没有路径、查询参数或片段的源；其他情况都会导致服务在启动时停止。
UNIFI_CONFIRM_WRITES	true	启用时，破坏性工具需要 confirm: "YES"。只有 false、0、no 或 off（不区分大小写）会将其关闭。未设置、为空、true、1、yes 和 on 时会保持启用；未知值也会保持启用，并记录警告。
UNIFI_TIMEOUT_MS	30000	单次请求超时时间（毫秒），涵盖响应标头和响应正文
UNIFI_LOG_LEVEL	info	debug | info | warn | error
UNIFI_CONSOLE_ID	（未设置）	覆盖自动发现（固定到特定控制台；当帐户拥有多个控制台或拥有其他类型的主机时需要设置）
UNIFI_NETWORK_SITE_ID	（未设置）	覆盖自动发现（固定到特定 Network 站点）
UNIFI_SITE_MANAGER_SITE_ID	（未设置）	覆盖自动发现（固定到特定 Site Manager 站点）
UNIFI_READ_ONLY	false	启用时，每个带有 confirm 参数的工具（所有写入工具，以及方法不是 GET 的 unifi_raw_request）都会返回包含 code: "READ_ONLY" 的错误，且不会发送请求；这些工具仍会列出。可使用与 UNIFI_CONFIRM_WRITES 相同的值；未知值会启用只读模式并记录警告。
UNIFI_REDACT_SECRETS	false	启用时，每个工具结果中，确认预览会隐藏的字段（密码、WiFi 密码短语、预共享密钥、机密、令牌、密钥）都会替换为 (redacted)；nextToken 等分页令牌会保留。MCP 资源（unifi://hosts、unifi://identity）不会隐藏。写入工具始终拒绝包含占位符的正文（参见“写入安全性”）。可使用与 UNIFI_READ_ONLY 相同的值。
UNIFI_MAX_RESULT_BYTES	100000	工具结果文本超过此 UTF-8 字节数时，会截断至此长度，并以 ... (truncated: ...) 标记结尾，其中会注明分页参数。未设置或为空：使用默认值（约 25,000 个 JSON 令牌）。0、off 或 none（不区分大小写）：不设上限。正整数会设置上限；其他任何值都会导致服务在启动时停止。MCP 资源不会被截断。

Claude Desktop 配置

将以下内容添加到 claude_desktop_config.json（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "unifi": {
      "command": "npx",
      "args": ["-y", "the-real-unifi-mcp"],
      "env": {
        "UNIFI_API_KEY": "<your Site Manager API key>"
      }
    }
  }
}

配置中的任何变量都可以放入 env。如果从源代码检出版本运行，请改用 "command": "node" 和 "args": ["--env-file=/absolute/path/to/the-real-unifi-mcp/.env", "/absolute/path/to/the-real-unifi-mcp/dist/index.js"]。

编辑文件后，重启 Claude Desktop。服务会在 unifi 前缀下提供工具。

Claude Code 配置

使用 Claude Code CLI 注册服务（--scope user 会使其在每个项目中均可用；默认范围 local 则仅对你在当前项目中可用）：

claude mcp add --scope user unifi --env UNIFI_API_KEY="YOUR_SITE_MANAGER_API_KEY" -- npx -y the-real-unifi-mcp

从源代码检出版本运行：

claude mcp add --scope user unifi -- node \
  --env-file=/absolute/path/to/the-real-unifi-mcp/.env \
  /absolute/path/to/the-real-unifi-mcp/dist/index.js

claude mcp list 会显示连接状态。

工具参考

Site Manager 手动封装工具（10 个）

直接调用 api.ui.com 的账户级工具：

• unifi_sm_list_hosts：列出账户上的所有 UniFi 控制台（可选 pageSize、nextToken）
• unifi_sm_get_host：获取单个控制台的详细信息
• unifi_sm_list_sites：账户级站点（可选 pageSize、nextToken）；除非设置 includeStatistics: true，否则会省略每个站点的 statistics 对象
• unifi_sm_list_devices：账户级设备列表（可选 hostIds、time、pageSize、nextToken）
• unifi_sm_get_isp_metrics：按时间桶（5m/1h）获取 ISP 指标，可指定 beginTimestamp/endTimestamp 或 duration（24h、7d、30d）
• unifi_sm_query_isp_metrics：在指定时间范围内查询 ISP 指标
• unifi_sm_list_sdwan_configs：SD-WAN 配置列表
• unifi_sm_get_sdwan_config：获取单个 SD-WAN 配置
• unifi_sm_get_sdwan_config_status：获取 SD-WAN 配置状态
• unifi_sm_identity：解析得到的 consoleId、networkSiteId、siteManagerSiteId

Network 手动封装工具（76 个）

通过 Cloud Connector 代理调用的逐控制台工具，按资源分组。每个 unifi_net_list_* 工具都支持可选的 offset、limit 和 filter（供应商筛选语法）；如果结果包含更多条目，则会附带含有下一偏移量的 pagination 提示。

• 信息 / 站点（2 个）： unifi_net_get_info、unifi_net_list_sites
• 设备（9 个）： unifi_net_list_devices、unifi_net_get_device、unifi_net_get_device_stats、unifi_net_list_pending_devices、unifi_net_adopt_devices、unifi_net_device_action、unifi_net_reboot_device、unifi_net_port_action、unifi_net_remove_device
• 客户端（5 个）： unifi_net_list_clients、unifi_net_get_client、unifi_net_client_action、unifi_net_block_client、unifi_net_unblock_client（阻止/解除阻止会返回“not supported”错误：Network API 不提供此类客户端操作）
• 网络（6 个）： unifi_net_list_networks、unifi_net_get_network、unifi_net_get_network_references、unifi_net_create_network、unifi_net_update_network、unifi_net_delete_network
• WiFi 广播（5 个）： unifi_net_list_wifi、unifi_net_get_wifi、unifi_net_create_wifi、unifi_net_update_wifi、unifi_net_delete_wifi
• 防火墙（13 个）： unifi_net_list_firewall_zones、unifi_net_get_firewall_zone、unifi_net_create_firewall_zone、unifi_net_update_firewall_zone、unifi_net_delete_firewall_zone、unifi_net_list_firewall_policies、unifi_net_get_firewall_policy、unifi_net_create_firewall_policy、unifi_net_update_firewall_policy、unifi_net_patch_firewall_policy、unifi_net_delete_firewall_policy、unifi_net_get_firewall_policy_ordering、unifi_net_reorder_firewall_policies
• ACL 规则（7 个）： unifi_net_list_acl_rules、unifi_net_get_acl_rule、unifi_net_create_acl_rule、unifi_net_update_acl_rule、unifi_net_delete_acl_rule、unifi_net_get_acl_rule_ordering、unifi_net_reorder_acl_rules
• DNS 策略（5 个）： unifi_net_list_dns_policies、unifi_net_get_dns_policy、unifi_net_create_dns_policy、unifi_net_update_dns_policy、unifi_net_delete_dns_policy
• 流量匹配列表（5 个）： unifi_net_list_traffic_lists、unifi_net_get_traffic_list、unifi_net_create_traffic_list、unifi_net_update_traffic_list、unifi_net_delete_traffic_list
• 热点优惠券（5 个）： unifi_net_list_vouchers、unifi_net_get_voucher、unifi_net_create_vouchers、unifi_net_delete_voucher、unifi_net_delete_vouchers
• 交换（6 个）： unifi_net_list_switch_stacks、unifi_net_get_switch_stack、unifi_net_list_mclag_domains、unifi_net_get_mclag_domain、unifi_net_list_lags、unifi_net_get_lag
• 辅助工具（8 个）： unifi_net_list_wans、unifi_net_list_site_to_site_vpn、unifi_net_list_vpn_servers、unifi_net_list_radius_profiles、unifi_net_list_device_tags、unifi_net_list_dpi_application_categories、unifi_net_list_dpi_applications、unifi_net_list_countries

自动生成的工具（82 个）

命名为 unifi_gen_<operationid>（供应商的 operationId，全部小写，例如 unifi_gen_createfirewallpolicy、unifi_gen_getinfo）。每个有文档记录的 UniFi API 端点对应一个工具（Site Manager API v1.0.0、Network API v11.0.97）；Site Manager 的 connector* 代理端点除外，这些由 unifi_raw_request 覆盖。siteId 会根据发现结果自动解析；调用方无需传入。写入工具会在 body schema 中记录供应商请求体，但与 0.2.1 一样，会接受并原样发送任何 body 值。除非设置 includeStatistics: true，否则 unifi_gen_listsites 会省略每个站点的 statistics 对象，这与 unifi_sm_list_sites 一致。完整清单请参见 src/tools/generated/。

应急通道（1 个）

unifi_raw_request(method, path, body?, query?)：向 api.ui.com{path} 执行任意 HTTP 方法。路径必须是相对路径；有关拒绝请求的情形，请参见 SECURITY.md。身份验证、重试、错误解析和分页提示都会自动处理。没有专用工具时可使用此工具。它会原样返回响应：此处的 GET /v1/sites 会保留 unifi_sm_list_sites 默认省略的 statistics 对象。

错误

调用失败时会返回错误结果，其 details 中包含 HTTP statusCode（未收到响应时为 0），并在已知时包含 code：该代码可能来自 UniFi API，也可能是 NETWORK_ERROR、REDIRECT_REFUSED、TIMEOUT 或 CANCELLED（客户端取消了调用）。

资源

• unifi://identity：解析出的 consoleId、两个 siteIds 和控制台元数据
• unifi://hosts：账户主机列表
• unifi://hosts/{id}：单个主机的详细信息

提示词

• unifi-audit-firewall：遍历防火墙区域和策略，标记薄弱规则并建议加固
• unifi-network-health：已配置的 WAN、各状态的设备数量和待处理的固件更新、按类型统计的已连接客户端，以及最近连接的客户端
• unifi-adoption-status：待采纳设备报告，并提供采纳/拒绝建议

写入安全

默认情况下（未设置 UNIFI_CONFIRM_WRITES 或其值为 true），破坏性工具需要显式传入 confirm: "YES"；否则会返回预览，其中请求体内的密码、WiFi 密码短语、预共享密钥、机密、令牌和密钥都会替换为 (redacted)。设置 UNIFI_CONFIRM_WRITES=false 可让破坏性工具直接执行。无论这些设置如何，写入工具都会拒绝任何值恰好为 (redacted) 的请求体字段，无论其嵌套深度如何（这是 UNIFI_REDACT_SECRETS 和预览使用的占位符）：工具会返回包含这些字段路径、code: "REDACTED_PLACEHOLDER" 的错误，并且不会进行预览或发送请求，因此开启脱敏读取的对象不会用占位符覆盖密码短语。请设置真实值或省略该字段：

{
  "data": {
    "preview": {
      "tool": "unifi_net_create_vouchers",
      "method": "POST",
      "url": "/v1/connector/consoles/.../proxy/network/integration/v1/sites/.../hotspot/vouchers",
      "body": { "count": 1, "name": "demo" }
    },
    "hint": "Write confirmation is on (UNIFI_CONFIRM_WRITES). Re-run with `confirm: \"YES\"` to apply this change."
  }
}

每个写入工具还支持 dry_run: true：它会返回相同的预览，且绝不执行，即使同时传入 confirm: "YES" 或设置了 UNIFI_CONFIRM_WRITES=false 也是如此。设置 UNIFI_READ_ONLY=true 时，写入工具会以 code: "READ_ONLY" 拒绝操作且不会发送任何内容；读取工具仍可正常使用。

模型可以自行发送 confirm: "YES"，因此此防护是针对模型的第二道步骤，并非人工审批。如果你希望亲自审批每次写入，请在 MCP 客户端中为写入工具开启逐工具审批（所有写入工具都带有 destructiveHint: true）。

示例

安装服务后，可将以下提示词粘贴到 Claude 中：

• “显示我所有的 UniFi 网络及其 VLAN ID。”
• “我有哪些 UniFi 设备目前处于离线状态？”
• “审查我的防火墙安全态势：按区域分组规则，并标记任何允许任意来源到任意目标的规则。”
• “重启名为 AP-Office-1 的接入点。”
• “对名为 SW-Office 的交换机上的 PoE 端口 3 执行断电重启。”

破坏性操作示例遵循 UNIFI_CONFIRM_WRITES（默认为 true）：模型会先获取预览，然后必须再次调用并传入 confirm: "YES" 才能应用更改。

限制

• 仅限云端。 所有请求都通过 Site Manager API 和 Network Cloud Connector 代理发送到 UniFi 云端点（api.ui.com）。不支持直接连接控制器或通过本地网络连接。
• 单个账户，且只能发现自己拥有的控制台。 发现功能会解析 API 密钥所属的控制台。拥有多个控制台或多个站点的账户必须通过 UNIFI_*_ID 变量固定 ID（参见故障排除）。
• 自动生成的工具与已发布的文档保持一致。 unifi_gen_* 工具根据 UniFi 文档中列出的端点生成；其输入架构的准确性取决于上游文档。若端点的实际行为与架构所述不同，请使用 unifi_raw_request。
• Network API 需要较新的固件。 Network API 仅适用于运行固件版本 ≥ 5.0.3 的控制台。
• 不支持事件流或 websockets。 工具仅支持请求/响应；不支持实时事件订阅。

故障排除

“Discovery: no console found …” 发现功能会选择密钥所属的 console 类型主机；只有在不存在此类主机时，才会选择所属的 ucore 类型主机（UniFi OS Server）。如果控制台属于其他类型，或密钥没有所属主机，请设置 UNIFI_CONSOLE_ID=<id>（即 unifi_sm_list_hosts 返回的 id）。

“Discovery: multiple consoles match …” 你的 Site Manager 账户有多个 UniFi 控制台。请将 UNIFI_CONSOLE_ID=<id> 设置为所列 ID 之一。多个 Network 站点（UNIFI_NETWORK_SITE_ID）或多个 Site Manager 站点（UNIFI_SITE_MANAGER_SITE_ID）的情况也采用相同方式处理。

401 Unauthorized API 密钥缺少 Network 作用域或已被撤销。请前往 unifi.ui.com 重新生成密钥，并启用 Site Manager 和 UniFi Applications → Network 两个作用域。任何曾在聊天或提交记录中暴露过的密钥都应轮换。

Claude Desktop 中未显示工具 编辑 claude_desktop_config.json 后，请重启 Claude Desktop；配置更改仅在启动时加载。MCP 日志位于 ~/Library/Logs/Claude/mcp-server-unifi.log（macOS）；请检查其中是否有启动错误或发现失败记录。

发送超大请求后服务立即停止 如果单条传入消息超过行长度限制，MCP SDK 会关闭 stdio 传输（参见 SECURITY.md）；随后进程会在 stderr 中记录 stdio transport closed 并以代码 1 退出，且不会返回错误结果。请拆分输入（例如减少 MAC 地址数量，或缩小每次调用的请求体），然后重启服务。

开发

npm run dev                  # tsx watch
npm run test:unit            # unit tests (offline; what prebuild runs)
npm test                     # unit tests (offline; the live smoke is not part of it)
npm run test:integration     # live read-only smoke against api.ui.com (only with UNIFI_LIVE=1 and UNIFI_API_KEY)
npm run codegen              # download the vendor OpenAPI docs and regenerate src/tools/generated/ (see CONTRIBUTING.md first)
npm run inspector            # MCP Inspector
npm run build:mcpb           # build MCPB bundle + SBOMs into release/
npm run lint                 # ESLint (type-aware, src, tests, scripts)
npm run typecheck            # tsc --noEmit (src), then tsconfig.tests.json (tests, scripts)

完整工作流请参见 CONTRIBUTING.md。

架构

三层工具设计。 手写封装工具（unifi_sm_*、unifi_net_*）为常见操作提供易用、文档完善的入口，并自动解析 ID，支持命名参数。82 个自动生成的工具（unifi_gen_*）涵盖代码生成目录（src/codegen/catalog.ts）中列出的端点，其输入架构源自上游 UniFi 文档。unifi_raw_request 则用于处理前两层未涵盖的情况。

按需发现 ID。 首次使用时，服务会调用 GET /v1/hosts 查找所属控制台（类型为 console；若没有匹配的控制台，则使用 ucore），然后调用 GET /v1/sites（Network 和 Site Manager）发现两个 siteId。结果会在进程生命周期内缓存。并发调用方通过已存储的 Promise 共享同一个进行中的请求。可通过环境变量固定全部三个 ID，以支持多控制台／多站点账户。

重试。 每个请求最多尝试 3 次。所有方法遇到 429 时都会重试，并遵循 Retry-After（最长 60 s），因为服务端已拒绝该请求。遇到 5xx 和连接中断时，仅 GET 会重试；POST、PUT、PATCH 或 DELETE 仅在网络错误导致连接从未建立时才会重新发送（例如 ECONNREFUSED、ENOTFOUND），因此可能已经到达 UniFi 的写入请求绝不会重复执行。重定向会被拒绝（API 密钥不会离开已配置的主机），超时不会重试。网络故障会作为包含原因的错误返回，并以 warn 级别记录。

代码生成流水线。 独立的构建步骤（npm run codegen）会下载供应商的 OpenAPI 文档（developer.ui.com/<api>/<version>/openapi.json）到 tests/fixtures/openapi/，将目录中的每个操作转换为 Zod 架构，并为每个端点生成一个 .ts 文件。只有所有目录条目均成功时才会写入文件；如果遇到既未列入目录也未排除的供应商操作，流程就会失败。npm run codegen -- --offline 会使用已提交的文档重新生成；单元测试会检查已提交的输出是否逐字节一致。输出位于 src/tools/generated/，并已提交到 git，以便离线构建。

安全

• API 密钥仅从 UNIFI_API_KEY 环境变量读取，绝不硬编码。
• .env 已加入 gitignore。
• 在 env 中保存密钥的 MCP 客户端配置（例如 claude_desktop_config.json）会以纯文本形式存储密钥；请妥善保管该文件。
• stderr 日志记录器会对已知的机密信息模式（UNIFI_API_KEY=...、X-API-Key、Authorization、apiKey、api_key，以及查询参数中的 api_key／apikey／token／access_token）进行脱敏，并按精确值对配置的 API 密钥进行脱敏，无论密钥出现在哪里。其他工具写入的输出不在此保护范围内。
• 请求路径相对于已配置的 UNIFI_API_BASE 源站；该地址必须使用 https://（仅用于环回测试桩时才可使用普通 http://）；API 密钥只会发送到该源站，并且重定向会被拒绝。
• 来自 UniFi API 的错误文本会像日志行一样脱敏，并在传递给模型前截断至固定长度。
• 请保持 UNIFI_CONFIRM_WRITES=true（默认值），以便对破坏性操作进行确认。
• 工具结果中包含由任何有权在你的 UniFi 设置中命名事物的人所控制的字符串（设备名称、客户端主机名、SSID、规则描述）。服务指令会告知模型将这些内容视为数据；你的 MCP 客户端仍应在执行破坏性工具前征求你的确认。威胁模型见 SECURITY.md。

如需报告漏洞，请使用 GitHub Security Advisories；请勿公开提交 issue。另请参阅 SECURITY.md。

维护状态

• 由一位维护者（@mguttmann）在业余时间尽力维护。不提供支持合同，也不保证响应时间。
• 安全修复优先于功能开发。请私下报告漏洞（参见安全）。
• 依赖项更新由 Dependabot 提供；当运行时依赖项存在已知的高危或严重安全公告时，CI 会失败。
• 仅为最新的次要版本提供修复。
• unifi_gen_* 工具遵循已发布的 UniFi API 文档；Ubiquiti 更改 API 后，这些工具会在后续版本中重新生成。待处理事项列于 BACKLOG.md。
• 欢迎提交问题和拉取请求；请参阅 CONTRIBUTING.md 和行为准则。

参与贡献

请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。tests/fixtures/openapi/ 中的供应商 OpenAPI 文档（Ubiquiti 的开发者文档）不受 MIT 许可证约束；请参阅 NOTICE。