UniFi

---

“为什么客厅电视一直在缓冲？” 电视连接在客厅 AP 上，信号强度为 -78 dBm，速率为 12 Mbps；该 AP 的 5 GHz 无线电在信道 36 上的信道利用率为 81%。将 AP 切换到信道 149，或添加有线回程，应该就能解决问题。要我更改信道吗？

用日常语言询问您的网络。助手会从 145 个工具中选择合适的工具来查询信息；如果您允许，也会进行更改。例如：

• 🩺 “检查一下网络的运行状况。”
• 🔎 “目前哪些客户端的 WiFi 信号较弱？”
• 🔐 “检查我的防火墙和端口转发，看看有没有风险。”
• 🔄 “哪些设备有固件更新？它们上次重启是什么时候？”
• 🎟️ “创建 10 个限速为 5 Mbps、有效期为一天的访客券。”
• 🧱 “封锁名为 'kids-tablet' 的设备，直到我解除封锁。”

亮点

• 🐳 Docker 优先。 提供一个小巧的 distroless 镜像（ghcr.io/mattoddie/unifi-mcp，约 22 MB），适用于 linux/amd64 和 linux/arm64。长期运行的服务可使用 Streamable HTTP；也可通过 docker run -i 使用 stdio。Claude Desktop 还可使用一键安装的扩展包（.mcpb），无需 Docker。
• 🛡️ 默认安全。 除非启用写入功能，否则服务为只读；删除配置还需要启用另一个开关。破坏性工具会明确标记，以便您的 MCP 客户端在执行前征求确认；输出中的密码和密钥会被隐藏。
• 🔍 预览与审计。 每个写入工具都支持 dry_run: true，可显示将要发送的请求，并以字段级差异展示将发生的更改，而不会实际修改任何内容。UNIFI_AUDIT_LOG 会将每项更改记录到 JSON Lines 审计日志中。
• 🧰 覆盖面广。 涵盖 14 个工具集：设备、客户端、交换机端口和 PoE、WiFi、网络和 VLAN、WAN、DNS、传统防火墙和基于区域的防火墙、流量规则和路由、IDS/IPS、VPN、RADIUS、热点访客券、统计信息、日志、管理员和备份。
• 🎛️ 可调节。 只公开所需的工具集，让模型上下文保持精简、聚焦。请参阅精简工具列表。
• 🔌 兼容您的控制器。 支持 UniFi OS 主机（UDM、UDM Pro/SE、UCG、UDR、UX、Cloud Key Gen2+、UniFi OS Server）以及传统的自托管 Network 应用。可通过 API 密钥或本地账户进行身份验证。
• 🧪 经过测试。 每次构建都会针对模拟控制器运行测试套件。

快速开始

你需要 Docker、UniFi 控制器和 MCP 客户端，例如 Claude Code。

1. 获取凭据。 在 UniFi OS 主机上创建 API 密钥：UniFi Network → Settings → Control Plane → Integrations → Create API Key。在较旧的控制器上，请改用本地账户。

2. 启动服务。

mkdir unifi-mcp && cd unifi-mcp
curl -fsSLO https://raw.githubusercontent.com/mattoddie/unifi-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/unifi-mcp/main/example.env -o .env
# Edit .env: set UNIFI_URL, UNIFI_API_KEY and a random MCP_AUTH_TOKEN (required; e.g. `openssl rand -hex 32`).
# For an https controller, also say how to check its certificate, or the server won't start.
# Recommended: pin it with UNIFI_TLS_FINGERPRINT (see docs/security.md). example.env sets
# UNIFI_VERIFY_SSL=false, which skips the check: remove it once the fingerprint is set.
docker compose up -d

3. 连接助手。

claude mcp add --transport http unifi http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

现在在 Claude Code 中询问 “我的网络运行得怎么样？”

使用 Claude Desktop、VS Code、Cursor 或 Codex？请参阅连接 MCP 客户端。不想运行服务？使用 docker run -i 配合 stdio 模式。

一键安装 Claude Desktop

在装有 Claude Desktop 的 Mac 或 Windows 电脑上，你完全不需要 Docker。从最新版本下载适用于你电脑的 .mcpb 安装包，打开后在设置中输入控制器 URL、API 密钥和证书指纹。请参阅 Claude Desktop。

unifi-mcp 也已列入 MCP Registry，名称为 io.github.mattoddie/unifi-mcp，其中包含镜像（通过 stdio 使用）和安装包，因此读取该注册表的客户端和目录都可以安装它。

启用更改

默认情况下，助手只能查看，不能操作。要允许它进行更改，请将以下内容添加到 .env 并运行 docker compose up -d：

UNIFI_ALLOW_WRITES=true      # restart devices, block clients, edit WiFi/firewall/networks…
UNIFI_ALLOW_DELETES=true     # also allow deleting configuration, forgetting clients… (needs writes too)
UNIFI_TOOLSETS=overview,devices,clients,wifi,monitoring   # optional: expose fewer tools
UNIFI_AUDIT_LOG=stderr       # optional: log every change (or a file path; see docs/configuration.md)

先请求试运行来预览更改：“试运行：禁用访客 WiFi。会有哪些变化？” 在为生产网络启用写入操作前，请阅读安全。

功能

工具集	涵盖内容
overview	站点、控制器信息、站点健康状况
devices	设备状态和详细信息、重启/定位/配置、固件升级（包括滚动升级）、无线电、PoE 插座、接管、RF 扫描、AP 组
clients	在线和已知客户端、封禁/解除封禁、重新连接、名称、固定 IP、锁定到 AP、忘记
switching	交换机端口、端口配置文件、PoE 电源循环、端口镜像、链路聚合、LLDP 邻居
wifi	WLAN（SSID、安全、VLAN、频段）、WiFi 二维码
networks	网络/VLAN 和 DHCP、WAN、本地 DNS 记录、带宽配置文件、动态 DNS
firewall	端口转发、防火墙规则和组、基于区域的策略和区域、流量规则、QoS 规则、NAT 规则、交换机 ACL 规则、面向对象的网络策略
routing	静态路由、基于策略的流量路由
security	IDS/IPS 威胁管理、威胁日志、国家/地区封锁、内容过滤
vpn	VPN 服务端和站点到站点 VPN、RADIUS 配置文件和账户
hotspot	凭证券、热点运营者、访客授权、访客门户
monitoring	事件、警报、流量报告、流量流、DPI、速度测试、恶意 AP、系统日志、会话、异常、仪表板
admin	站点设置（包括 SNMP、mDNS 和自动备份）、管理员、备份、控制器更新、站点
raw	可调用控制器任意 API 路径的备用入口

如需查看每个工具及其参数，请参阅**工具参考**。network_health_check、troubleshoot_client 和 security_review 等现成提示词会串联多个工具，以完成常见任务。

文档

文档也发布在 unifi-mcp.mattoddie.dev/docs，并提供搜索功能。

🚀 快速入门	分步配置指南，从凭据到提出第一个问题
🔌 连接 MCP 客户端	Claude Code、Claude Desktop、VS Code、Cursor、Codex、stdio 模式
⚙️ 配置	所有环境变量、Docker secrets、工具集
🐳 部署	Compose、镜像标签、升级、TLS 反向代理、加固
💬 使用 unifi-mcp	对话示例、提示词、保存和密钥的工作方式
🧰 工具参考	全部 145 个工具和 5 个提示词，均根据代码生成
🛡️ 安全	威胁模型、最小权限、安全的写入配置
📡 兼容性	支持的控制器和版本、API 注意事项
🩹 故障排除	常见错误及其解决方法
🛠️ 开发	架构、添加工具、测试

参与贡献

欢迎各种贡献，包括错误报告、硬件兼容性报告、文档或新工具。请阅读贡献指南以开始参与，并遵守行为准则。如需报告漏洞，请参阅安全政策。请勿为此公开创建 issue。

许可证

MIT © Matt Oddie

unifi-mcp 是一个独立的社区项目，与 Ubiquiti Inc. 无关，未获其认可或赞助。UniFi 和 Ubiquiti 是 Ubiquiti Inc. 的商标。