sirkirby/unifi-mcp

# UniFi MCP

利用 agent 和 agentic AI 工作流管理您的 UniFi 部署。 [](https://pypi.org/project/unifi-network-mcp/) [](https://pypi.org/project/unifi-protect-mcp/) [](https://pypi.org/project/unifi-access-mcp/) [](https://pypi.org/project/unifi-mcp-relay/) [](https://pypi.org/project/unifi-api-server/) [](https://www.npmjs.com/package/unifi-mcp-worker) [](LICENSE) [](https://www.python.org/downloads/) ## 服务 | 服务 | 状态 | 工具 | 包 | |--------|--------|-------|---------| | [Network](apps/network/) | 稳定版 | 186 | [`unifi-network-mcp`](https://pypi.org/project/unifi-network-mcp/) | | [Protect](apps/protect/) | 测试版 | 61 | [`unifi-protect-mcp`](https://pypi.org/project/unifi-protect-mcp/) | | [Access](apps/access/) | 测试版 | 36 | [`unifi-access-mcp`](https://pypi.org/project/unifi-access-mcp/) | ## 云中继 | 组件 | 状态 | 包 | |-----------|--------|---------| | [Relay Sidecar](https://github.com/sirkirby/unifi-mcp/tree/main/packages/unifi-mcp-relay) | 测试版 | [`unifi-mcp-relay`](https://pypi.org/project/unifi-mcp-relay/) | | [Worker Gateway](https://github.com/sirkirby/unifi-mcp/tree/main/apps/worker) | 测试版 | [`unifi-mcp-worker`](https://www.npmjs.com/package/unifi-mcp-worker) (CLI) | Cloud Relay 将托管在 Cloudflare 的 Worker gateway 与您局域网 (LAN) 上的 Relay sidecar 配对。Worker 提供经过身份验证的边缘 MCP endpoint、Durable Object broker、多位置路由、token 边界以及部署/管理 CLI。Relay sidecar 是一个本地 MCP HTTP 客户端和转发器：它通过 HTTP 发现已配置的本地 MCP 服务器，并与 Worker 保持出站 WebSocket 连接。远程请求遵循 `MCP client → Worker gateway → outbound WebSocket → Relay sidecar → local MCP servers over HTTP` 的路径；API 服务器不在此路径中。只读工具支持基于 annotation 的多位置扇出，而写入操作则需要明确指定目标位置。使用 `npm install -g unifi-mcp-worker && unifi-mcp-worker install` 部署 Worker，然后查阅 [Relay sidecar README](packages/unifi-mcp-relay/) 以连接本地服务器。 ## REST + GraphQL API (非 MCP) | 组件 | 状态 | 包 | |-----------|--------|---------| | [API Server](https://github.com/sirkirby/unifi-mcp/tree/main/apps/api) | 测试版 | [`unifi-api-server`](https://pypi.org/project/unifi-api-server/) · [GHCR 镜像](https://github.com/sirkirby/unifi-mcp/pkgs/container/unifi-api-server) | `unifi-api-server` 是一个独立的 HTTP 服务，专为不使用 MCP 协议的消费者设计。它提供强类型的 REST 资源、只读 GraphQL 查询、SSE 流、作用域 API key 和管理功能，以及用于支持控制器操作的 REST action endpoint。它与 MCP 服务器共享 `unifi-core` 管理器，但既不代理也不依赖于它们。 有关快速入门和部署模式，请参阅 [`apps/api/README.md`](apps/api/README.md)。 ## 这是什么？ UniFi MCP 是一组 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，允许 AI 助手和自动化工具与 Ubiquiti UniFi 控制器进行交互。每个服务器都针对特定的 UniFi 应用程序（Network、Protect、Access），并将其功能作为 MCP 工具公开——默认情况下是可查询、可组合且安全的。 ## MCP 发现 UniFi MCP 将标准 MCP 路径作为主要方式：支持此功能的客户端可以通过 `tools/list` 发现当前注册的工具，并通过 `tools/call` 调用它们。默认的 `lazy` 模式通过优先公开 meta-tools 来保持初始上下文精简，而 `eager` 模式则直接为偏好完整标准工具列表的客户端注册所有选定的域工具。 延迟加载的 meta-tools —— `*_tool_index`、`*_execute`、`*_batch`、`*_batch_status` 以及仅限 lazy 模式的 `*_load_tools` —— 支持过滤发现、间接执行、批量编排和可选的直接注册。它们独立于下文提到的协议版本响应兼容性策略。有关各模式的具体行为，请参阅 [MCP 发现和延迟加载 Meta-Tools](docs/tool-index.md)。 ## MCP 响应大小 对于已经提供结构化输出的工具结果，默认采用 `adaptive` 响应模式。它根据 MCP 初始化时发布的、基于规范日期的 `protocolVersion` 对每个请求进行分类，而不是根据客户端的产品名称或应用程序版本。声明为 MCP `2025-06-18` 或更高版本的请求，会在 `content` 中接收简洁文本，并在 `structuredContent` 中接收一次完整结果；声明为较早版本（例如 `2024-11-05` 或 `2025-03-26`）的请求，或者其版本元数据缺失/格式错误的请求，将在 `content` 中保留完整的兼容性 JSON。设置 `UNIFI_MCP_CONTENT_MODE=compat` 可强制使用该重复的兼容性格式，或者设置 `UNIFI_MCP_CONTENT_MODE=compact` 以强制输出简洁文本加上完整的结构化结果（即使在非协商请求中也是如此）。如果客户端仅从 `content` 获取完整结果，请使用 `compat` 模式，无论其声明的版本是什么。 延迟加载的 meta-tools 仍然只提供内容；它们不属于上述 `2025-06-18` 之前的协议类别。对于结构化的内部结果，`*_execute` 和 `*_batch_status` 会在 `content` 中公开一个标准化的 JSON payload，而不是嵌套的传输对；仅限内容的执行结果保持不变。响应模式不会将这些 meta-tools 转换为 `structuredContent`。 `UNIFI_NETWORK_MCP_CONTENT_MODE`、`UNIFI_PROTECT_MCP_CONTENT_MODE` 和 `UNIFI_ACCESS_MCP_CONTENT_MODE` 会分别覆盖各自服务器的全局设置。独立于传输压缩之外，Network 的 `unifi_get_dashboard` 默认设置为 `summary=true`，而 `unifi_list_rogue_aps` 默认返回最多 100 条记录的摘要页面；当需要完整的所选数据时，请传入 `summary=false`。 ## 快速开始 ### Claude Code (推荐) 通过插件市场安装 —— 包括 MCP 服务器、agent 技能和引导式设置： ``` /plugin marketplace add sirkirby/unifi-mcp /plugin install unifi-network@unifi-plugins /unifi-network:unifi-network-setup ``` 如有需要，重复此过程以安装 Protect 或 Access： ``` /plugin install unifi-protect@unifi-plugins /plugin install unifi-access@unifi-plugins ``` 每个插件的设置命令都会引导您连接到控制器并配置权限。 ### Codex 注册 UniFi MCP 市场，然后从 Codex 的 `/plugins` UI 中安装插件： ``` codex plugin marketplace add sirkirby/unifi-mcp ``` 启动 `codex`，运行 `/plugins`，打开 UniFi MCP 市场并安装 `unifi-network`、`unifi-protect` 或 `unifi-access`。安装后，要求 Codex 运行该插件的设置技能，例如： 设置技能会使用 `codex mcp add` 注册 MCP 服务器，将选定的环境变量值存储在 Codex 的 MCP 配置中，并保持与 Claude Code 相同的“预览后再确认”的安全模型。 ### UniFi 账户要求 MCP 服务器使用本地管理员/服务账户对本地 UniFi 控制器 API 进行身份验证。请勿在 MCP 设置中使用 Ubiquiti SSO 云账户。目前，对于 Network MCP，不支持通过配置使用需要 SSO MFA 或本地 2FA 的账户；请为服务账户使用未开启 MFA 的专用本地管理员账户，并根据您愿意授予 MCP 服务器的权限范围进行限制。 ### OpenClaw OpenClaw 可以从市场安装相同的 UniFi 插件包，并将它们的技能和 MCP 服务器定义映射到内嵌的 Pi 会话中： ``` openclaw plugins install unifi-network --marketplace https://github.com/sirkirby/unifi-mcp openclaw gateway restart ``` 然后从 OpenClaw 运行匹配的设置技能（`unifi-network-setup`、`unifi-protect-setup` 或 `unifi-access-setup`），或者直接配置服务器： ``` openclaw mcp set unifi-network '{ "command": "uvx", "args": ["--python-preference", "system", "unifi-network-mcp@latest"], "env": { "UNIFI_NETWORK_HOST": "192.168.1.1", "UNIFI_NETWORK_USERNAME": "admin", "UNIFI_NETWORK_PASSWORD": "your-password" } }' ``` 根据需要，使用 `unifi-protect` 或 `unifi-access` 重复此操作。更改 MCP 服务器配置后，请重启 OpenClaw Gateway。 ### 其他 MCP 客户端 直接运行服务器： ``` uvx unifi-network-mcp@latest uvx unifi-protect-mcp@latest uvx unifi-access-mcp@latest ``` 对于 Claude Desktop，请将其添加到您的 `claude_desktop_config.json` 中： ``` { "mcpServers": { "unifi-network": { "command": "uvx", "args": ["unifi-network-mcp@latest"], "env": { // Server-specific vars take priority; UNIFI_* is the fallback "UNIFI_NETWORK_HOST": "192.168.1.1", "UNIFI_NETWORK_USERNAME": "admin", "UNIFI_NETWORK_PASSWORD": "your-password" } }, "unifi-protect": { "command": "uvx", "args": ["unifi-protect-mcp@latest"], "env": { "UNIFI_PROTECT_HOST": "192.168.1.1", "UNIFI_PROTECT_USERNAME": "admin", "UNIFI_PROTECT_PASSWORD": "your-password" } }, "unifi-access": { "command": "uvx", "args": ["unifi-access-mcp@latest"], "env": { "UNIFI_ACCESS_HOST": "192.168.1.1", "UNIFI_ACCESS_USERNAME": "admin", "UNIFI_ACCESS_PASSWORD": "your-password" } } } } ``` ## 使用示例 连接后，只需用自然语言向您的 AI agent 提问： **Network** **Protect** **Access** **跨产品** (为了获得完整体验，需要 [relay](packages/unifi-mcp-relay/)) 所有修改操作都采用 **预览后确认** 流程 —— 在应用任何更改之前，您都能确切地看到将要发生什么变化。 ## 配置 设置这些环境变量（或使用 `.env` 文件）： | 变量 | 是否必需 | 描述 | |----------|----------|-------------| | `UNIFI_HOST` | 是 | 控制器 IP 或主机名 | | `UNIFI_USERNAME` | 是 | 本地管理员/服务账户用户名；请勿使用 Ubiquiti SSO 账户 | | `UNIFI_PASSWORD` | 是 | 本地账户密码 | | `UNIFI_API_KEY` | 否 | 用于特定功能的 UniFi API key，包括防火墙策略排序和某些 Protect 设置更新 | ### 多控制器设置 每个服务器都支持各自带前缀的环境变量，这些变量优先于共享的 `UNIFI_*` 变量。这允许您将 Network 和 Protect 服务器指向不同的控制器（或使用不同的凭据），同时保留一个 `.env` 文件： | 共享（回退） | Network 服务器 | Protect 服务器 | Access 服务器 | |--------------------|----------------|----------------|---------------| | `UNIFI_HOST` | `UNIFI_NETWORK_HOST` | `UNIFI_PROTECT_HOST` | `UNIFI_ACCESS_HOST` | | `UNIFI_USERNAME` | `UNIFI_NETWORK_USERNAME` | `UNIFI_PROTECT_USERNAME` | `UNIFI_ACCESS_USERNAME` | | `UNIFI_PASSWORD` | `UNIFI_NETWORK_PASSWORD` | `UNIFI_PROTECT_PASSWORD` | `UNIFI_ACCESS_PASSWORD` | | `UNIFI_PORT` | `UNIFI_NETWORK_PORT` | `UNIFI_PROTECT_PORT` | `UNIFI_ACCESS_PORT` | | `UNIFI_VERIFY_SSL` | `UNIFI_NETWORK_VERIFY_SSL` | `UNIFI_PROTECT_VERIFY_SSL` | `UNIFI_ACCESS_VERIFY_SSL` | | `UNIFI_API_KEY` | `UNIFI_NETWORK_API_KEY` | `UNIFI_PROTECT_API_KEY` | `UNIFI_ACCESS_API_KEY` | **单控制器？** 只需设置共享的 `UNIFI_*` 变量 —— 所有服务器都将使用它们。只有当服务器与不同的控制器通信或使用不同的凭据时，才需要服务器特定的变量。 有关包含权限、传输和高级选项的完整配置参考，请参阅 [Network 服务器文档](apps/network/docs/configuration.md)、[Protect 服务器文档](apps/protect/docs/configuration.md) 或 [Access 服务器文档](apps/access/docs/configuration.md)。 ## 敏感信息脱敏 工具和 API 响应默认会对已知的控制器敏感字段进行脱敏处理 —— Wi-Fi 密码、VPN 私钥/预共享密钥、完整的 VPN 配置块（导入的 WireGuard/OpenVPN `.conf`/`.ovpn` 文件）、API token、SNMP 社区字符串以及 Access 凭据 token/PIN 值将返回为 `***REDACTED***。这使得敏感信息不会出现在 agent 上下文和日志中。 当受信任的本地管理工作流程确实需要原始值时，可以通过设置 `UNIFI_REDACT_SENSITIVE_FIELDS=false` 或服务器特定的覆盖项（例如 `UNIFI_NETWORK_REDACT_SENSITIVE_FIELDS=false`、`UNIFI_PROTECT_REDACT_SENSITIVE_FIELDS=false`、`UNIFI_ACCESS_REDACT_SENSITIVE_FIELDS=false` 或 `UNIFI_API_REDACT_SENSITIVE_FIELDS=false`）来禁用该过程的脱敏。要在更新期间保留现有的机密信息，只需省略该字段 —— **切勿**将 `***REDACTED*** 标记传回；系统会拒绝此类操作，以确保占位符永远不会被写成真实的机密信息。有关脱敏字段的完整列表，请参阅 [`PRIVACY.md`](PRIVACY.md)。 ## Agent 技能 每个插件都附带了超越原始工具访问权限的 agent 技能 —— 它们能教导 agent 如何有效地执行常见任务： | 技能 | 插件 | 功能 | |-------|--------|-------------| | **Network Health Check** | unifi-network | 跨设备、健康子系统和告警的批量诊断，并附带用于解读结果的参考文档 | | **Firewall Manager** unifi-network | 基于自然语言的防火墙管理，包含策略模板、配置快照和更改跟踪 | | **Firewall Auditor** | unifi-network | 包含 16 项基准检查、100 分制评分、拓扑分析和趋势跟踪的安全审计 | | **Security Digest** | unifi-protect | 跨产品事件情报 —— 总结摄像头、门禁和网络事件，包含严重性分类和关联规则 | | **UniFi Access** | unifi-access | 门禁控制、凭据、访客、访问策略 —— 具备实时事件流和活动摘要 | 技能包括参考文档（设备状态、告警类型、防火墙 schema、事件目录）和用于确定性操作（审计、配置导出/diff、模板应用）的 Python 脚本。 ## 架构 这是一个包含共享包的 monorepo： ``` apps/ network/ # UniFi Network MCP server (stable, 186 tools) protect/ # UniFi Protect MCP server (beta, 61 tools) access/ # UniFi Access MCP server (beta, 36 tools) api/ # Independent REST + GraphQL API server (beta) worker/ # Cloudflare Worker gateway + npm CLI packages/ unifi-core/ # Shared UniFi connectivity (auth, detection, retry) unifi-mcp-shared/ # Shared MCP patterns (permissions, tools, diagnostics, config) unifi-mcp-relay/ # Cloud relay sidecar (bridges local servers to Cloudflare Worker) plugins/ unifi-network/ # Claude Code/Codex/OpenClaw plugin: MCP server + agent skills + setup unifi-protect/ # Claude Code/Codex/OpenClaw plugin: MCP server + agent skills + setup unifi-access/ # Claude Code/Codex/OpenClaw plugin: MCP server + setup skills/ _shared/ # Shared utilities for skill scripts (MCP client, config) docs/ # Ecosystem-level documentation ``` `apps/` 中的每个 Python 服务器都是依赖于共享包的独立包。`apps/worker/` 是有意单独设立的：它是一个独立的 TypeScript/Node 应用程序，用于 Cloudflare Worker gateway 和 npm CLI。将其保留在此代码库中是为了让中继协议的更改和 Worker 契约测试能够同步推进。 详情请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 开发 ``` make sync # Install Python workspace + worker npm dependencies make check # Format check + lint + generated drift checks + tests + worker typecheck make build # Build deployable artifacts, including worker typecheck ``` ## 支持本项目 UniFi MCP 作为独立的开源项目进行维护。赞助有助于支付构建、测试和维护项目过程中持续产生的 AI 成本，以及 Network、Protect、Access、API、中继和插件包的实时控制器兼容性测试、版本维护、文档撰写和问题分类整理。 - [在 GitHub 上赞助](https://github.com/sponsors/sirkirby) - [查看赞助资金用途](https://unifimcp.com/sponsor/) ## 许可证 [MIT](LICENSE)

标签：AI智能体, Docker 部署, MCP服务器, MITM代理, Python, UniFi, 无后门, 物联网管理, 程序员工具, 网络运维, 逆向工具