UniFi RMCP

unifi-rmcp

通过 MCP 和 CLI 执行 UniFi Network 客户端、设备、WLAN、防火墙和运行状况操作。

它提供一个 MCP 工具 unifi，以及 runifi CLI。Agent 可以检查 客户端、设备、WiFi 网络、运行状况、警报、事件、控制器系统信息和 已认证身份；在 MCP 身份验证范围允许时，还可以使用生成的 official_* / unifi_* 操作。

**30 秒上手：**设置 UNIFI_URL 和 UNIFI_API_KEY，然后运行 npx -y @dinglebear/runifi health --json -> 启动回环 HTTP 服务： UNIFI_MCP_HOST=127.0.0.1 npx -y @dinglebear/runifi serve -> 调用 tools/call，参数为 {"action":"health"}。

**状态：**可运行的 RMCP 上游客户端服务。保留的便捷操作以读取为主；生成的变更操作需要 unifi:admin 授权。HTTP MCP 支持回环开发模式、静态 Bearer 令牌，以及通过 lab-auth 进行 Google OAuth。

**不适用于：**替代 UniFi 控制台、为调用方存储控制器凭据、绕过 UniFi 权限、通用 HTTP 代理、多租户隔离，或通过 MCP 工具参数传递 UniFi API 密钥。

目录

• 命名
• 功能与边界
• 安装
• 快速开始
• 客户端配置
• 运行时接口
• MCP 工具参考
• CLI 参考
• 配置
• 身份验证
• 安全与信任模型
• 架构
• 分发约定
• 开发
• 验证
• 部署
• 故障排除
• 相关服务
• 文档
• 许可证

命名

接口	本仓库
仓库	unifi-rmcp
Rust crate	unifi-rmcp
二进制文件 / CLI	runifi
npm 包	@dinglebear/runifi
npm 二进制别名	unifi-rmcp、runifi
MCP 工具	unifi
配置目录	主机上为 ~/.unifi-rmcp，容器中为 /data
环境变量前缀	npm 启动器控制项使用 UNIFI_*、UNIFI_MCP_*、UNIFI_RMCP_*

仓库和 npm 包使用 RMCP 系列名称，而发布的二进制文件使用简短的 Rust CLI 名称 runifi。

功能与边界

• 读取已连接的无线和有线客户端、网络设备、WLAN 配置、 站点运行状况、活动警报、近期事件、控制器系统信息和当前 已认证用户。
• 调用针对有文档说明的 Network Integration API 端点生成的 official_* 操作。
• 调用由模型支持的 unifi_* 控制器内部操作，以及 list_clients、list_devices、list_networks、list_wifi 和 get_system_info 等混合别名。
• 在挂载的 HTTP MCP 模式下，对读取操作强制要求 unifi:read，对变更操作强制要求 unifi:admin。
• 提供设置、诊断和端点验证命令，用于本地运行时检查。

本仓库负责	UniFi 负责	明确不在范围内
MCP/CLI 投影、操作注册表、请求验证、HTTP MCP 身份验证策略、响应整形、生成的操作分发、设置检查和端点验证。	控制器状态、站点/设备/客户端数据、UniFi 用户、API 密钥签发、上游授权和实际网络变更。	替代控制器 UI、凭据代理、任意 HTTP 代理、长期轮询、策略即代码、多租户隔离沙箱和本地网关配置。

安装

路径	命令	适用场景	备注
npm / npx	npx -y @dinglebear/runifi --help	本地 MCP 客户端和快速试用。	从 GitHub Releases 下载匹配的 runifi 二进制文件。
Release 安装程序	curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/runifi/main/scripts/install.sh | bash	无需 Node 的主机安装。	为当前 Linux 主机安装 runifi。
Docker / Compose	docker compose up -d	共享的 HTTP MCP 部署。	读取 .env 并公开容器端口 40030。
从源代码构建	cargo build --release	开发和审计。	生成 target/release/runifi。
插件	claude plugin install plugins/unifi	从此检出版本进行 Claude Code 本地插件设置。	随附技能和 .mcp.json。没有会话钩子——插件设置通过 .mcp.json 的 ${user_config.*} 环境变量块传递给服务，因此无需手动设置。

npm / npx

无需手动安装二进制文件，即可运行 stdio MCP 服务或 CLI：

npx -y @dinglebear/runifi --help
npx -y @dinglebear/runifi mcp
npx -y @dinglebear/runifi health --json

npm 包会在 postinstall 期间下载 runifi。仅在测试打包时覆盖下载行为：

变量	用途
UNIFI_RMCP_SKIP_DOWNLOAD=1	跳过 postinstall 二进制文件下载。
UNIFI_RMCP_VERSION 或 UNIFI_RMCP_BINARY_VERSION	选择 GitHub Release 标签。
UNIFI_RMCP_REPO	选择用于下载 Release 的 GitHub 仓库。
UNIFI_RMCP_RELEASE_BASE_URL	选择自定义 Release 基础 URL。

从源代码构建

git clone [email protected]:dinglebear-ai/runifi.git
cd runifi
cargo build --release
./target/release/runifi --help

最低支持的 Rust 版本：1.86。Cargo 工作区包含三个成员： 根目录下的 unifi-rmcp 包、crates/unifi（可复用核心）和 xtask （开发工具）。所有成员都继承工作区根目录中的 Rust 2024 版和 MSRV 1.97.1。

快速入门

1. 创建 UniFi API 密钥

在 UniFi OS 中，前往 Settings -> Admins & Users -> API Keys，创建密钥，并将其 复制到 UNIFI_API_KEY。

2. 配置控制器

export UNIFI_URL=https://unifi.local
export UNIFI_API_KEY=...
export UNIFI_SITE=default
export UNIFI_SKIP_TLS_VERIFY=true

仅当使用较旧的非 UDM 控制器且不使用 /proxy/network 路径前缀时，才设置 UNIFI_LEGACY=true。

3. 执行安全的 CLI 调用

npx -y @dinglebear/runifi health --json

4. 启动回环 HTTP MCP

UNIFI_MCP_HOST=127.0.0.1 npx -y @dinglebear/runifi serve

在另一个 Shell 中：

curl -sf http://127.0.0.1:40030/health

5. 发起首次 MCP 调用

curl -s -X POST http://127.0.0.1:40030/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"unifi","arguments":{"action":"health"}}}'

客户端配置

Claude Code Stdio

{
  "mcpServers": {
    "unifi": {
      "command": "npx",
      "args": ["-y", "unifi-rmcp", "mcp"],
      "env": {
        "UNIFI_URL": "https://unifi.local",
        "UNIFI_API_KEY": "...",
        "UNIFI_SITE": "default",
        "UNIFI_SKIP_TLS_VERIFY": "true"
      }
    }
  }
}

Claude Code HTTP

{
  "mcpServers": {
    "unifi": {
      "type": "http",
      "url": "http://127.0.0.1:40030/mcp",
      "headers": {
        "Authorization": "Bearer ${UNIFI_MCP_TOKEN}"
      }
    }
  }
}

Codex / Labby Gateway

通过 Labby 将 UniFi 注册为 HTTP 上游，以便共享一个长期运行的服务；也可以将其直接作为 stdio 运行，仅供本地使用。

[mcp_servers.unifi]
command = "npx"
args = ["-y", "unifi-rmcp", "mcp"]

通用 MCP JSON

{
  "command": "runifi",
  "args": ["mcp"],
  "env": {
    "UNIFI_URL": "https://unifi.local",
    "UNIFI_API_KEY": "..."
  }
}

不要将 UNIFI_API_KEY、OAuth 密钥、密码、SSH 密钥或上游承载令牌放入 MCP 工具参数中。请使用环境变量、配置文件或 MCP 客户端的密钥存储。MCP 调用方绝不会将凭据、令牌、密钥或机密作为操作参数提供。

运行时接口

接口	状态	入口点	用途
MCP stdio	支持	runifi mcp, npx -y @dinglebear/runifi mcp	本地子进程 MCP 客户端。
MCP HTTP	支持	runifi serve, POST /mcp	用于本地或共享服务部署的可流式 HTTP MCP。
CLI	支持	runifi <command>	可编写脚本的功能对等性和调试。
提示词	支持	network_summary	用于生成 UniFi 状态摘要的 Agent 提示词。
资源	支持	MCP 工具架构资源	客户端侧架构发现。
REST API	未提供	N/A	UniFi 已提供 REST API。
Web UI	未提供	N/A	UniFi 已提供控制器 UI。

MCP 工具参考

此处公开了一个 MCP 工具：unifi。传入必需的 action 参数以选择操作。操作枚举由 data/ 中的清单生成，因此涵盖范围较广：

类型	操作数	可变更
official_*	78	36
unifi_*	175	87
保留的便捷操作	8	0
混合别名	5	0
help	1	0
总计	267	123

计数依据 data/unifi_official_network_v10_3_58.json 和 data/unifi_internal_endpoint_models.json 中 runtime: true 的条目得出。 crates/unifi/src/capabilities.rs 是运行时的唯一事实来源。

保留的便捷操作

操作	描述	必需参数	可选参数
clients	已连接的无线和有线客户端。	无	无
devices	网络设备：AP、交换机、网关。	无	无
wlans	WiFi 网络配置。	无	无
health	站点运行状况摘要。	无	无
alarms	活跃的告警和提醒。	无	无
events	最近的控制器事件。	无	limit
sysinfo	控制器系统信息。	无	无
me	已验证身份的 UniFi 用户信息。	无	无
help	内置操作文档。	无	无

生成的操作类型

类型	描述	范围行为
official_*	/proxy/network/integration/v1 下有文档说明的 Network Integration API 操作。	读取操作需要 unifi:read；可变更操作需要 unifi:admin。
unifi_*	/proxy/network/api/s/{site} 和 /proxy/network/v2/api/site/{site} 下基于模型的控制器兼容操作。	读取操作需要 unifi:read；可变更操作需要 unifi:admin。
混合别名	list_clients、list_devices、list_networks、list_wifi、get_system_info。	默认使用内部操作；若提供 siteId 或 params.prefer="official"，则使用官方 API。

端点覆盖情况记录在 docs/unifi_api_coverage.md 中；契约和安全的实时验证说明见 docs/unifi_endpoint_verification.md。

CLI 参考

此二进制程序调用的服务层与 MCP 工具相同：

runifi clients [--json]
runifi devices [--json]
runifi wlans [--json]
runifi health [--json]
runifi alarms [--json]
runifi events [--limit N] [--json]
runifi sysinfo [--json]
runifi me [--json]
runifi official_list_clients --param siteId=<uuid> --json
runifi official_create_network --param siteId=<uuid> --body-json '{"name":"IoT"}' --json
runifi list_clients --param siteId=<uuid> --json
runifi doctor [--json]
runifi setup check [--json]
runifi setup repair [--json]
runifi setup install [--json]
runifi setup plugin-hook [--no-repair] [--json]

生成的操作支持 --param k=v、--body-json JSON 和 --json。

setup plugin-hook 会将 CLAUDE_PLUGIN_OPTION_* 环境变量映射到 UNIFI_*， 刷新 ~/.local/bin 中的二进制副本，并运行检查和修复。它过去会通过 Claude Code SessionStart/ConfigChange 钩子自动运行；这些钩子现已移除。

配置插件无需运行此命令：plugins/unifi/.mcp.json 会通过 ${user_config.*} 将插件设置直接映射到服务的环境变量。仅当你需要刷新 ~/.local/bin 中的二进制程序或运行预检时，才手动执行此命令。

配置

配置首先从 config.toml 加载，然后由 UNIFI_* 环境变量覆盖。主机安装会在加载配置前读取 ~/.unifi-rmcp/.env；容器会读取 /data/.env。进程环境变量的优先级高于两者。

变量	默认值	用途
UNIFI_URL	未设置	控制器基础 URL，例如 https://unifi.local。
UNIFI_API_KEY	未设置	用于 X-API-KEY 标头的 API 密钥。
UNIFI_SITE	default	UniFi 站点名称。
UNIFI_SITE_ID	未设置	官方 API 站点 UUID，由实时测试和显式生成的调用使用。
UNIFI_SKIP_TLS_VERIFY	true	跳过对使用自签名证书的控制器进行 TLS 证书验证。
UNIFI_LEGACY	false	不带 /proxy/network 前缀的旧版控制器模式。
UNIFI_MCP_HOST	0.0.0.0	HTTP 绑定主机。
UNIFI_MCP_PORT	40030	HTTP 绑定端口。
UNIFI_MCP_TOKEN	未设置	HTTP MCP 的静态 bearer 令牌。
UNIFI_MCP_NO_AUTH	false	仅在本地回环开发时禁用身份验证。
UNIFI_MCP_DISABLE_HTTP_AUTH	false	UNIFI_MCP_NO_AUTH 的兼容别名。
UNIFI_NOAUTH	false	信任上游网关强制执行身份验证。
UNIFI_MCP_ALLOWED_HOSTS	空	以逗号分隔的 Host 标头允许列表。
UNIFI_MCP_ALLOWED_ORIGINS	空	以逗号分隔的 CORS Origin 允许列表。
UNIFI_MCP_PUBLIC_URL	未设置	OAuth 元数据的公共 URL。
UNIFI_MCP_AUTH_MODE	bearer	bearer 或 oauth。
UNIFI_MCP_GOOGLE_CLIENT_ID	未设置	Google OAuth 客户端 ID。
UNIFI_MCP_GOOGLE_CLIENT_SECRET	未设置	Google OAuth 客户端密钥。
UNIFI_MCP_AUTH_ADMIN_EMAIL	未设置	OAuth 引导配置使用的管理员邮箱。
UNIFI_MCP_AUTH_SQLITE_PATH	/data/auth.db	OAuth 状态数据库路径。
UNIFI_MCP_AUTH_KEY_PATH	/data/auth-jwt.pem	OAuth JWT 签名密钥路径。
UNIFI_MCP_HOME	~/.unifi-rmcp	应用数据目录覆盖项；仅由 setup 读取。

仅在 config.toml 中设置且没有环境变量覆盖项的选项：mcp.server_name 以及 [mcp.auth] 中的 TTL、速率限制和允许列表字段 （access_token_ttl_secs、refresh_token_ttl_secs、auth_code_ttl_secs、 register_rpm、authorize_rpm、disable_static_token_with_oauth、 allowed_emails、allowed_client_redirect_uris）。请参阅 config.example.toml。

xtask 端点验证会读取自身使用的变量，服务器不会读取这些变量：UNIFI_ALLOW_INSECURE_TLS、UNIFI_RESOLVE_IP、 UNIFI_VERIFY_TIMEOUT_SECS、UNIFI_VERIFY_RATE_LIMIT_MS、 UNIFI_VERIFY_MAX_REQUESTS、UNIFI_VERIFY_UNVERIFIED_INTERNAL。

身份验证

Stdio MCP 作为本地可信子进程运行，不使用 HTTP 身份验证。

HTTP MCP 身份验证策略：

状态	条件	行为
本地回环开发	UNIFI_MCP_HOST 以 127. 开头，或在本地回环环境中明确禁用了身份验证	允许在本地进行未验证身份的开发。
已挂载 bearer	非本地回环环境且设置了 UNIFI_MCP_TOKEN	需要 Authorization: Bearer <token> 和操作作用域。
已挂载 OAuth	UNIFI_MCP_AUTH_MODE=oauth	通过 lab-auth 使用 Google OAuth/JWT。
可信网关	UNIFI_NOAUTH=true	假定反向代理或网关已执行身份验证。

unifi:admin 包含 unifi:read 的权限；unifi:read 无法执行会修改数据的操作。

安全与信任模型

• UniFi API 密钥仅从配置/环境变量加载。
• MCP 调用方可以选择操作、参数和请求正文，但不能选择上游凭据。
• 保留的便捷操作以读取为主。
• 在已挂载的 HTTP MCP 模式下，生成的修改操作需要 unifi:admin。
• 未知操作和格式错误的生成操作参数会在调用上游之前失败。
• 非本地回环的 HTTP 部署必须使用 bearer 身份验证、OAuth 或可信的已验证身份网关。
• 此桥接不会对 UniFi 本身进行沙箱隔离。UniFi 仍负责 API 权限以及修改调用在网络端实际造成的影响。

架构

Capabilities   (src/capabilities.rs)   official/internal/hybrid registry
      |
UnifiClient    (src/api.rs, src/unifi.rs) HTTP path families and transport
      |
UnifiService   (src/app.rs)            action execution boundary
      |
MCP shim       (src/mcp/tools.rs)      JSON args -> service -> Value
CLI shim       (src/cli.rs)            argv -> service -> stdout

发布约定

• Cargo.toml、Cargo.lock、packages/unifi-rmcp/package.json、 .release-please-manifest.json 和 server.json 中的发布版本必须一致。
• GitHub Releases 会发布供 npm 启动器使用的 runifi 二进制文件。
• npm 包名为 @dinglebear/runifi；二进制别名为 @dinglebear/runifi 和 runifi。
• Docker/OCI 元数据使用 ghcr.io/dinglebear-ai/runifi:<version>。GHCR 命名空间仍为 jmagar，因为 .github/workflows/docker-publish.yml 发布到该命名空间；Git 远程仓库为 dinglebear-ai/runifi。不要单独“修正”其中一项。
• plugins/unifi/.mcp.json 必须启动 npx -y @dinglebear/runifi mcp，以便 stdio 客户端启动 MCP 传输，而不是 HTTP 服务。
• plugins/unifi/ 不包含 Claude Code hooks。若 hooks/ 目录或清单中的 hooks 键重新出现，scripts/validate-plugin-layout.sh 和 tests/setup_cli.rs 都会失败。
• 根目录 README 经过精心整理。当前操作和生成的端点覆盖范围以 src/capabilities.rs、data/ 清单、 docs/unifi_api_coverage.md 和 docs/unifi_endpoint_verification.md 为准。

开发

cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release
npm --prefix packages/unifi-rmcp run check

验证

npm --prefix packages/unifi-rmcp run check
cargo check
cargo test
cargo clippy -- -D warnings
just validate-plugin
cargo run -p xtask -- verify-api-endpoints --mode contract
git diff --check

实时读取探测需要控制器：

UNIFI_URL=https://<gateway> \
UNIFI_API_KEY=<network-api-key> \
UNIFI_SITE=default \
UNIFI_SITE_ID=<official-site-uuid> \
UNIFI_SKIP_TLS_VERIFY=true \
cargo run -p xtask -- verify-api-endpoints --mode safe_live

部署

本地开发请使用回环地址：

UNIFI_MCP_HOST=127.0.0.1 runifi serve

共享 HTTP 部署请使用 Docker Compose：

cp .env.example .env
docker compose up -d

绑定到非回环地址时，请配置 UNIFI_MCP_TOKEN、 UNIFI_MCP_AUTH_MODE=oauth，或在经过身份验证的网关后设置 UNIFI_NOAUTH=true。

故障排除

症状	检查
缺少 UNIFI_URL 或 UNIFI_API_KEY	在环境变量中或 ~/.unifi-rmcp/.env 中设置。
连接 UniFi 控制器时出现 TLS 错误	除非控制器具有受信任的证书，否则请保持 UNIFI_SKIP_TLS_VERIFY=true。
旧版控制器路径失败	对较旧的非 UDM 控制器设置 UNIFI_LEGACY=true。
HTTP /mcp 返回未授权	设置 UNIFI_MCP_TOKEN，并发送 Authorization: Bearer <token>。
Stdio 客户端挂起或记录 JSON 错误	确保客户端配置运行 unifi-rmcp mcp，而不是默认的 HTTP 服务模式。
生成的官方操作需要 siteId	传入 --param siteId=<uuid> 或 MCP params.siteId。
禁止执行生成的变更操作	使用具有 unifi:admin 权限的 HTTP MCP 令牌/会话。

相关服务

所有同级服务都位于 dinglebear-ai 组织下。

• soma - 用于由提供方支持的 MCP 服务的 RMCP 运行时和脚手架。
• rtailscale - 用于设备、用户和 tailnet 操作的 Tailscale API 桥接服务。
• unraid - Unraid 单体仓库；unraid-rs/ 是 GraphQL 桥接服务（二进制文件 runraid）。
• rapprise - Apprise 通知扇出桥接服务，支持多种发送后端。
• rgotify - 用于发送、消息、应用和客户端的 Gotify 推送通知桥接服务。
• rarcane - 用于容器及相关资源的 Arcane Docker 管理桥接服务。
• yarr - 面向 Sonarr、Radarr、Prowlarr、Plex 及相关服务的媒体栈桥接服务。
• rytdl - 媒体下载和元数据工作流服务。
• synapse - 用于 scout 和 flux 操作的本地 Synapse 工作流服务。
• cortex - Syslog 和家庭实验室日志聚合 MCP 服务。
• axon - RAG、爬取、抓取、提取和语义搜索项目。
• labby - 家庭实验室控制平面和 MCP 网关项目。

文档

• CLAUDE.md 是为贡献者和 Agent 编写的精选本地操作指南。
• docs/unifi_api_coverage.md 是精选的 API 系列与覆盖范围摘要。
• docs/unifi_endpoint_verification.md 是精选的端点验证指南。
• docs/SETUP.md 是精选的插件和设置指南。
• docs/OAUTH.md 是精选的 OAuth 设置指南。
• plugins/unifi/skills/unifi/SKILL.md 是 Agent 使用指南。
• data/ 清单是为操作注册表生成的参考输入。
• src/ 是当前操作分发、配置默认值、身份验证行为和 CLI 解析的事实来源。

许可证

本项目中由 Dinglebear 编写的原创部分采用 AGPL-3.0-only 许可。对于需要 AGPL 之外许可条款的组织，可提供单独的商业许可。第三方材料仍遵循其原始许可证。请参阅 LICENSING.md。