内容
# unifi-rmcp
`unifi-rmcp` 是一个用 Rust 编写的 MCP 服务器和 CLI，用于通过官方、内部和混合 UniFi API 操作来管理 Ubiquiti UniFi 网络控制器。
它暴露了一个 MCP 工具 `unifi` 和一个 CLI `runifi`。代理可以检查客户端、设备、WiFi 网络、健康状况、警报、事件、控制器系统信息和身份验证身份，并且可以在 MCP 授权范围内使用生成的 `official_*` / `unifi_*` 操作。
**30 秒路径：** 设置 `UNIFI_URL` 和 `UNIFI_API_KEY`，然后运行 `npx -y unifi-rmcp health --json` -> 使用 `UNIFI_MCP_HOST=127.0.0.1 npx -y unifi-rmcp serve` 启动循环 HTTP -> 调用 `tools/call` 并发送 `{"action":"health"}`。
**状态：** 运营中的 RMCP 上游客户端服务器。保留的便捷操作是只读的；生成的修改操作需要 `unifi:admin` 授权。HTTP MCP 支持循环开发模式、静态持有者令牌和 Google OAuth。
**不适用于：** 替换 UniFi 控制台、存储调用者的控制器凭证、绕过 UniFi 权限、通用 HTTP 代理、多租户隔离或通过 MCP 工具参数传递 UniFi API 密钥。
## 目录
- [命名](#命名)
- [功能和边界](#功能和边界)
- [安装](#安装)
- [快速入门](#快速入门)
- [客户端配置](#客户端配置)
- [运行时界面](#运行时界面)
- [MCP 工具参考](#mcp-工具参考)
- [CLI 参考](#cli参考)
- [配置](#配置)
- [身份验证](#身份验证)
- [安全性和信任模型](#安全性和信任模型)
- [架构](#架构)
- [分发合约](#分发合约)
- [开发](#开发)
- [验证](#验证)
- [部署](#部署)
- [故障排除](#故障排除)
- [相关服务器](#相关服务器)
- [文档](#文档)
- [许可证](#许可证)
## 命名
| 界面 | 此仓库 |
|---|---|
| 仓库 | `unifi-rmcp` |
| Rust 包 | `unifi-rmcp` |
| 二进制文件 / CLI | `runifi` |
| npm 包 | `unifi-rmcp` |
| npm 二进制文件别名 | `unifi-rmcp`, `runifi` |
| MCP 工具 | `unifi` |
| 配置首页 | 主机上的 `~/.unifi-rmcp`，容器中的 `/data` |
| 环境前缀 | `UNIFI_*`，`UNIFI_MCP_*`，`UNIFI_RMCP_*` 用于 npm 启动器控制 |
该仓库和 npm 包使用 RMCP 家族名称，而发布的二进制文件使用简短的 Rust CLI 名称 `runifi`。
## 功能和边界
- 读取连接的无线和有线客户端、网络设备、WLAN 配置、站点健康、活动警报、最近事件、控制器系统信息和当前身份验证用户。
- 分发生成的 `official_*` 操作，用于文档化的网络集成 API 端点。
- 分发模型支持的 `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 unifi-rmcp --help` | 本地 MCP 客户端和快速试验。 | 从 GitHub Releases 下载匹配的 `runifi` 二进制文件。 |
| 发布安装程序 | `curl -fsSL https://raw.githubusercontent.com/jmagar/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 本地插件设置。 | 使用打包的设置钩子、技能和本地运行时元数据。 |
### npm / npx
在不手动安装二进制文件的情况下运行 stdio MCP 服务器或 CLI：
```bash
npx -y unifi-rmcp --help
npx -y unifi-rmcp mcp
npx -y unifi-rmcp health --json
```
npm 包在 `postinstall` 期间下载 `runifi`。仅在测试打包时覆盖下载行为：
| 变量 | 目的 |
|---|---|
| `UNIFI_RMCP_SKIP_DOWNLOAD=1` | 跳过安装后二进制文件下载。 |
| `UNIFI_RMCP_VERSION` 或 `UNIFI_RMCP_BINARY_VERSION` | 选择 GitHub Release 标签。 |
| `UNIFI_RMCP_REPO` | 选择用于发布下载的 GitHub 仓库。 |
| `UNIFI_RMCP_RELEASE_BASE_URL` | 选择自定义发布基准 URL。 |
### 从源代码构建
```bash
git clone https://github.com/jmagar/runifi
cd unifi-rmcp
cargo build --release
./target/release/runifi --help
```
最低支持的 Rust 版本：1.86。
## 快速入门
### 1. 创建 UniFi API 密钥
在 UniFi OS 中，前往 设置 -> 管理员和用户 -> API 密钥，创建一个密钥，并将其复制到 `UNIFI_API_KEY`。
### 2. 配置控制器
```bash
export UNIFI_URL=https://unifi.local
export UNIFI_API_KEY=...
export UNIFI_SITE=default
export UNIFI_SKIP_TLS_VERIFY=true
```
仅为不使用 `/proxy/network` 路径前缀的旧非 UDM 控制器设置 `UNIFI_LEGACY=true`。
### 3. 运行安全 CLI 调用
```bash
npx -y unifi-rmcp health --json
```
### 4. 启动循环 HTTP MCP
```bash
UNIFI_MCP_HOST=127.0.0.1 npx -y unifi-rmcp serve
```
在另一个 shell 中：
```bash
curl -sf http://127.0.0.1:40030/health
```
### 5. 进行首次 MCP 调用
```bash
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
```json
{
"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
```json
{
"mcpServers": {
"unifi": {
"type": "http",
"url": "http://127.0.0.1:40030/mcp",
"headers": {
"Authorization": "Bearer ${UNIFI_MCP_TOKEN}"
}
}
}
}
```
### Codex / Labby 网关
通过 Labby 将 UniFi 注册为 HTTP 上游服务器，以共享一个长时间运行的服务器，或直接作为 stdio 运行以仅限本地使用。
```toml
[mcp_servers.unifi]
command = "npx"
args = ["-y", "unifi-rmcp", "mcp"]
```
### 通用 MCP JSON
```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 unifi-rmcp mcp` | 本地子进程 MCP 客户端。 |
| MCP HTTP | 支持 | `runifi serve`，`POST /mcp` | 可流式 HTTP MCP，用于本地或共享服务器部署。 |
| CLI | 支持 | `runifi <command>` | 可脚本化对齐和调试。 |
| 提示 | 支持 | `network_summary` | UniFi 状态摘要的代理提示。 |
| 资源 | 支持 | MCP 工具模式资源 | 客户端模式发现。 |
| REST API | 未提供 | N/A | UniFi 已经拥有 REST API。 |
| Web UI | 未提供 | N/A | UniFi 已经拥有控制器 UI。 |
## MCP 工具参考
公开一个 MCP 工具：`unifi`。传递所需的 `action` 参数以选择操作。
### 保留的便捷操作
| 操作 | 描述 | 要求参数 | 可选参数 |
|---|---|---|---|
| `clients` | 连接的无线和有线客户端。 | 无 | 无 |
| `devices` | 网络设备：AP、交换机、网关。 | 无 | 无 |
| `wlans` | WiFi 网络配置。 | 无 | 无 |
| `health` | 站点健康摘要。 | 无 | 无 |
| `alarms` | 活动警报和通知。 | 无 | 无 |
| `events` | 最近的控制器事件。 | 无 | `limit` |
| `sysinfo` | 控制器系统信息。 | 无 | 无 |
| `me` | 身份验证的 UniFi 身份。 | 无 | 无 |
| `help` | 内置操作文档。 | 无 | 无 |
### 生成的操作族
| 家族 | 描述 | 范围行为 |
|---|---|---|
| `official_*` | 文档化的网络集成 API 操作，位于 `/proxy/network/integration/v1` 下。 | 读取操作需要 `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 工具相同的服务层：
```bash
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]
```
生成的操作接受 `--param k=v`、`--body-json JSON` 和 `--json`。
## 配置
主机安装程序读取 `~/.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_SERVER_NAME` | `unifi-rmcp` | 公告的 MCP 服务器名称。 |
| `UNIFI_MCP_TOKEN` | 未设置 | HTTP MCP 的静态持有者令牌。 |
| `UNIFI_MCP_NO_AUTH` | `false` | 仅在循环开发中禁用身份验证。 |
| `UNIFI_NOAUTH` | `false` | 信任上游网关执行身份验证。 |
| `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 引导的管理员电子邮件。 |
## 身份验证
stdio MCP 作为本地受信任的子进程运行，不使用 HTTP 身份验证。
HTTP MCP 身份验证策略：
| 状态 | 条件 | 行为 |
|---|---|---|
| 循环开发 | `UNIFI_MCP_HOST` 以 `127.` 开头或在循环中显式禁用身份验证 | 允许本地无身份验证开发。 |
| 持有者挂载 | 非循环且设置了 `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 部署必须使用持有者身份验证、OAuth 或受信任的身份验证网关。
- 此桥接器不为 UniFi 本身提供沙盒。UniFi 仍然负责 API 权限和实际网络侧面的修改调用。
## 架构
```text
功能 (src/capabilities.rs) 官方/内部/混合注册
|
UniFiClient (src/api.rs, src/unifi.rs) HTTP 路径族和传输
|
UniFiService (src/app.rs) 操作执行边界
|
MCP 垫片 (src/mcp/tools.rs) JSON 参数 -> 服务 -> 值
CLI 垫片 (src/cli.rs) argv -> 服务 -> stdout
```
## 分发合约
- `Cargo.toml`、`Cargo.lock`、`packages/unifi-rmcp/package.json`、`release-please-manifest.json` 和 `server.json` 必须同意发布的版本号。
- GitHub Releases 发布 npm 启动器使用的 `runifi` 二进制文件。
- npm 包名称为 `unifi-rmcp`；二进制别名为 `unifi-rmcp` 和 `runifi`。
- Docker/OCI 元数据使用 `ghcr.io/jmagar/runifi:<version>`。
- `plugins/unifi/.mcp.json` 必须启动 `npx -y unifi-rmcp mcp`，以便 stdio 客户端启动 MCP 传输，而不是 HTTP 服务器模式。
- 根 README 经过策划。当前操作和生成端点覆盖的源信息是 `src/capabilities.rs`、`data/` 清单、`docs/unifi_api_coverage.md` 和 `docs/unifi_endpoint_verification.md`。
## 开发
```bash
cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release
npm --prefix packages/unifi-rmcp run check
```
## 验证
```bash
python3 /home/jmagar/workspace/soma/scripts/check-readme-guide.py README.md
npm --prefix packages/unifi-rmcp run check
cargo check
cargo test
cargo run -p xtask -- verify-api-endpoints --mode contract
git diff --check
```
需要控制器的实时读取探针：
```bash
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
```
## 部署
在本地开发中使用循环：
```bash
UNIFI_MCP_HOST=127.0.0.1 runifi serve
```
使用 Docker Compose 进行共享 HTTP 部署：
```bash
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 令牌/会话。 |
## 相关服务器
- [soma](https://github.com/jmagar/soma) - 用于提供者支持的 MCP 服务器的 RMCP 运行时。
- [tailscale-rmcp](https://github.com/jmagar/rtailscale) - 设备、用户和尾网操作的 Tailscale API 桥接器。
- [unraid-rmcp](https://github.com/jmagar/runraid) - 用于 NAS 和服务器管理的 Unraid GraphQL 桥接器。
- [apprise-rmcp](https://github.com/jmagar/rapprise) - 适用于多个投递后端的 Apprise 通知分发桥接器。
- [gotify-rmcp](https://github.com/jmagar/rgotify) - Gotify 发送通知的推送通知桥接器，适用于发送、消息、应用和客户端。
- [arcane-rmcp](https://github.com/jmagar/rarcane) - 适用于容器和相关资源的 Arcane Docker 管理桥接器。
- [yarr](https://github.com/jmagar/yarr) - 媒体栈的桥接器，适用于 Sonarr、Radarr、Prowlarr、Plex 和相关服务。
- [ytdl-rmcp](https://github.com/jmagar/rytdl) - 媒体下载和元数据工作流服务器。
- [synapse-rmcp](https://github.com/jmagar/synapse) - 本地 Synapse 工作流服务器，适用于侦察和通量操作。
- [cortex](https://github.com/jmagar/cortex) - 系统日志和家庭实验室日志聚合 MCP 服务器。
- [axon](https://github.com/jmagar/axon) - RAG、爬取、抓取、提取和语义搜索项目。
- [labby](https://github.com/jmagar/labby) - 家庭实验室控制平面和 MCP 网关项目。
- [lumen](https://github.com/jmagar/lumen) - 本地语义代码搜索 MCP 服务器。
## 文档
- `CLAUDE.md` 是为贡献者和代理人策划的本地操作指南。
- `docs/unifi_api_coverage.md` 是策划的 API 家族和覆盖率摘要。
- `docs/unifi_endpoint_verification.md` 是策划的端点验证指南。
- `docs/SETUP.md` 是策划的插件/设置指南。
- `docs/OAUTH.md` 是策划的 OAuth 设置指南。
- `plugins/unifi/skills/unifi/SKILL.md` 是代理使用指南。
- `data/` 清单是操作注册表的生成/参考输入。
- `src/` 是当前操作调度、配置默认值、身份验证行为和 CLI 解析的源代码。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器