unifi-mcp

UniFi MCP 服务

mcp-name: io.github.mikeholownych/unifi-mcp

一个 MCP（Model Context Protocol）服务，为 Claude 等 AI 助手提供 UniFi Network 和 Protect 基础设施管理与分析能力。它使用原生 MCP SDK 2 的 MCPServer API（而非 FastMCP 3），默认通过 stdio 通信。

鸣谢： 本项目最初是 gbassaragh/Unifi-mcp 的分支，后来发展为完全独立的项目。感谢 @gbassaragh 提供了出色的起点。

相较于上游版本的改进

• 修复本地会话身份验证路由 — 在 UNIFI_MODE=local 模式下，请求现在会正确使用传统控制器 API（/proxy/network）以及 Cookie + CSRF 会话身份验证。上游版本无论使用哪种模式，都会始终通过 Integration API 路由。
• 根据模式解析基础 URL — api_base_url 现在会遵循已配置的身份验证模式，而不是无条件返回 Integration API 端点。
• 扩展测试套件 — 通过 250 多项测试，覆盖配置、MCP 兼容性、运行时持久化、网络客户端行为、服务工具注册和 Protect 集成。

功能

UniFi Network

• 设备管理：列出、重启、定位和升级 UniFi 设备（AP、交换机、路由器）
• 客户端管理：监控已连接客户端、阻止/解除阻止客户端、查看流量统计信息
• 站点管理：查看站点运行状况、网络配置、VLAN 和无线设置
• 统计与监控：事件、警报、速度测试和 DPI 统计信息
• AI 驱动的洞察：网络分析、优化建议和故障排查

UniFi Protect

• 摄像头管理：列出摄像头、查看状态、获取实时快照
• 系统监控：NVR 状态、摄像头运行状况摘要
• 配件：管理灯具、传感器、门铃和查看器
• 实时视图：访问已配置的摄像头视图布局

多设备支持

• 配置多个 UniFi 设备（网关、NVR 等）
• 按名称指定目标设备 — 所有网络和 Protect 工具都接受可选的 device 参数
• 每台设备使用独立的 API 密钥：每台已配置设备都使用自己的密钥进行身份验证
• 支持在不同设备间混用 Network 和 Protect 服务

事件与安全自动化

• 在可选的 SQLite 存储中规范化并持久去重 Network 和 Protect 事件
• 独立轮询每个已配置的数据源，并明确报告不支持的功能
• 仅运行内置的间隔任务：poll_events、retry_webhook_deliveries、capture_observations 和 prune_runtime_data
• 发送经过筛选并签名的 HTTPS Webhook，支持有界重试和死信状态
• 默认禁用持久化、后台自动化和私有 Webhook 目标地址

认证模式

模式	认证方式	适用场景
local_api_key	集成 API 密钥	推荐的默认选项；拥有广泛的读取权限
local	用户名/密码会话	完整功能访问权限：防火墙规则、WLAN 配置、站点设置、事件、告警、DPI
cloud	api.ui.com 密钥	远程／云管理控制器

使用 API 密钥（集成 API）时，只有通过旧版会话认证（UNIFI_MODE=local）才能使用部分控制器功能：网络事件、告警、DPI 统计信息、速度测试、WLAN 配置、防火墙规则、端口配置文件和路由表。相关工具会清楚说明如何启用这些功能，而不会静默失败。洞察工具会优雅降级，并报告数据限制。

本地账户说明： 受 MFA 保护的 SSO／Ubiquiti 账户管理员无法完成会话登录。请在控制台上创建一个本地管理员（仅限本地访问），用于 UNIFI_MODE=local。

Agent 技能

随附的技能（位于 skills/ 中）会教 Agent 如何使用此服务执行经过验证的工作流，其中包括控制器特有的注意事项（Network 10 移除的端点、区域对规则、WPA3 过渡）。

完整文档：请参阅 SKILLS.md，了解使用指南、预期结果、故障排查以及如何申请新功能。

快速参考

技能	类型	用途
unifi-network-audit	只读	完整站点审计：设备、客户端、WiFi 安全状况、防火墙、结构化报告
unifi-troubleshoot-client	只读	诊断异常设备：RF、漫游、阻止状态、IP 层
unifi-wifi-optimize	写入需审批	信道规划、带宽、WPA3 过渡、频段引导——需审批
unifi-grant-device-access	写入需审批	为设备分配保留 IP，并授予范围受限的区域防火墙访问权限
unifi-internet-down	只读分诊	“互联网断了！”——通俗易懂的中断诊断、ISP 升级处理脚本
unifi-whos-home	只读	“谁在用我的 WiFi？”——友好的设备清单、考虑随机 MAC 地址的入侵者检查
unifi-setup-new-device	写入需审批	让任何新设备联网：配对问题（2.4GHz/WPA3）、命名、IP 保留
unifi-dns-triage	只读	“网站无法加载，但 ping 正常”——区分解析问题与连接问题、强制使用内部 DNS 的模式
unifi-mdns-discovery	只读+	跨 VLAN 的 AirPrint/Cast 无法使用——mDNS 反射、IGMP/IPTV 注意事项
unifi-port-forwarding	写入需审批	公开可自托管服务，包括发夹 NAT、CGNAT 检测、区域策略配对
unifi-vpn	写入需审批	WireGuard/Teleport 设置及故障排查步骤（握手/MTU/区域策略）
unifi-firmware-campaign	写入需审批	分阶段固件更新：快照、金丝雀验证、核验、卡住设备的排查步骤
unifi-mesh-backhaul	只读	远端房间 WiFi 速度慢：无线回程／跳数诊断、有线回程建议
unifi-ids-ips-triage	只读+	威胁告警：误报与真实威胁的区分、抑制、IPS 吞吐量开销
unifi-backup-migration	写入需审批	备份内容、迁移经验法则、迁移前快照
unifi-network-map	文档编写器	持久化的带标签拓扑图（区域/VLAN/依赖关系），让其他技能都更精准

技能如何运作

只需自然地描述你的问题，Agent 就会将你的请求匹配到合适的技能，并遵循其工作流：

• “我的网络断了” → unifi-internet-down 会诊断 WAN、调制解调器和网关
• “谁连着我的 WiFi？” → unifi-whos-home 会列出设备并标记未知设备
• “审查我的网络” → unifi-network-audit 会生成完整的健康报告
• “帮我设置新电视” → unifi-setup-new-device 会引导你配对 WiFi

需要写入权限的技能（如上方所标记）会修改你的网络——应用更改前总会征求批准。

面向非技术用户的技能会避免使用术语、解释每个技术术语，并在执行可能造成中断的操作前要求确认。

安装（每个项目）：复制到 .claude/skills/：

git clone https://github.com/mikeholownych/unifi-mcp.git
mkdir -p .claude/skills && cp -r unifi-mcp/skills/* .claude/skills/

完整的使用指南、预期结果、故障排除以及如何申请新功能，请参阅 SKILLS.md。

技能通过普通名称引用 MCP 工具（get_firewall_policies、……）； MCP 客户端会自动为其添加前缀。

支持的硬件

• UniFi Dream Machine（UDM、UDM-Pro、UDM-SE）
• UniFi Cloud Gateway（UCG-Ultra、UCG-Fiber）
• UniFi Network Video Recorder（UNVR、UNVR-Pro）
• UniFi Network Application（可自托管）
• 传统 Cloud Key（Gen1、Gen2、Gen2+）

限制与支持的版本

此服务面向可信的本地网络环境，通过 IP 地址连接 UniFi 控制台。需要注意以下几点：

• 默认禁用 TLS 验证（UNIFI_VERIFY_SSL=false）。UniFi OS 使用自签名证书，控制器通过局域网内的 IP 地址访问，因此证书验证通常会失败。只有当控制器提供受 CA 信任的证书时，才启用 UNIFI_VERIFY_SSL=true。
• 允许启动时未配置设备。 即使尚未提供 UNIFI_* 凭据（例如部署时通过环境变量进行配置），服务也会启动并公开所有工具。在设置设备之前，针对设备的工具调用会返回明确的 No device configured 错误。
• 范围强制执行仅适用于远程传输。 使用 Streamable HTTP 时，每个 tools/call 都会受读／写／管理员 OIDC 范围限制；如果有任何工具未分类，启动就会失败。使用 stdio（本地 IPC）时不需要身份验证——stdio 被视为可信的本地进程。
• 集成 API 密钥的限制。 部分控制器功能仅通过旧版会话身份验证（UNIFI_MODE=local）提供：网络事件、警报、DPI 统计信息、速度测试、WLAN／防火墙配置、端口配置文件和路由表。使用这些功能的工具会返回明确的错误，并说明如何启用它们。
• 已针对较新的 UniFi OS／Network／Protect 测试。 对于移除了旧版端点的较新控制器（例如 UniFi Network 10 移除了警报／事件端点），服务会通过优雅降级处理，而不会报错。
• 不能替代控制器备份。 快照和报告是只读导出，不能用于配置或恢复控制器。

安装

使用 uv（推荐）

# Clone the repository
git clone https://github.com/mikeholownych/unifi-mcp.git
cd unifi-mcp

# Install dependencies
uv sync

使用 pip

pip install -e .

配置

在项目根目录创建 .env 文件（或设置环境变量）。所有选项请参阅 .env.example。

UNIFI_CACHE_TTL 控制客户端实例间共享 GET 缓存的有效期（默认值：30 秒）。变更验证默认会执行五次全新读取，间隔依次为 0.5、1、 2 和 2 秒，并采用指数延迟。当控制器收敛速度更快或更慢时，可通过 UNIFI_MUTATION_VERIFY_ATTEMPTS、 UNIFI_MUTATION_VERIFY_INITIAL_DELAY 和 UNIFI_MUTATION_VERIFY_MAX_DELAY 调整这些设置。

可选运行时持久化

基于 SQLite 的运行时持久化默认处于禁用状态。仅在需要持久保存运行时状态时启用：

UNIFI_RUNTIME_ENABLED=true

默认情况下，数据库位于 UNIFI_DATA_DIR 下的 runtime.db。如果未设置 UNIFI_DATA_DIR，服务将遵循 XDG 数据目录约定：当 XDG_DATA_HOME 是绝对路径时使用 $XDG_DATA_HOME/unifi-mcp，否则使用 ~/.local/share/unifi-mcp。因此，默认数据库路径为 $XDG_DATA_HOME/unifi-mcp/runtime.db 或 ~/.local/share/unifi-mcp/runtime.db。

如有需要，可设置明确的数据目录或数据库路径：

UNIFI_DATA_DIR=/var/lib/unifi-mcp
UNIFI_RUNTIME_DATABASE=/var/lib/unifi-mcp/runtime.db

UNIFI_DATA_DIR 和 UNIFI_RUNTIME_DATABASE 必须解析为绝对路径。UNIFI_RUNTIME_DATABASE 会覆盖根据 UNIFI_DATA_DIR 推导出的数据库路径。

事件、计划任务和 Webhook

运行时持久化会启用事件存储和管理工具，但不会启动后台任务。请单独启用调度器：

UNIFI_RUNTIME_ENABLED=true
UNIFI_AUTOMATION_ENABLED=true

事件采集基于能力进行轮询，并不意味着 UniFi 普遍支持推送：

• Network 事件轮询需要使用 UNIFI_MODE=local 的传统本地会话身份验证。
• Protect 事件轮询要求为每台 Protect 设备配置本地 username 和 password。
• 集成 API 和云端 Network 配置会被报告为不支持事件轮询。
• 轮询会使用时间重叠加持久化源键去重，以避免时间戳边界导致重复记录。

计划任务只能调用 poll_events、retry_webhook_deliveries、capture_observations 或 prune_runtime_data。修改计划任务和 Webhook 需要设置 confirm=true；任意 MCP 工具名称、命令、导入项和表达式都会被拒绝。

Webhook 目标使用 HTTPS，不跟随重定向，并且会在每次尝试前解析和检查目标地址。除非设置 UNIFI_WEBHOOK_ALLOW_PRIVATE=true，否则会拒绝环回、私有、链路本地、多播和保留地址。即使 UniFi 控制器使用自签名证书，专用 Webhook 客户端仍会验证证书。

签名密钥不会进入 SQLite 或 MCP 参数。请在服务环境中设置密钥，然后仅将其变量名作为 secret_env_name 传入：

WEBHOOK_SECRET_AUTOMATION='replace-with-a-random-secret'

常用工具包括 get_event_polling_status、poll_events_now、list_runtime_events、create_interval_schedule、run_schedule_now、list_job_runs、create_webhook_destination、test_webhook_destination 和 list_webhook_deliveries。可重试的任务和 Webhook 失败会使用有上限的指数退避；超过重试上限的投递会进入 dead_letter 状态。

可移植快照和报告

可移植快照是由受支持的读取 API 汇总生成的版本化规范 JSON 导出文件。它包含来源范围、明确的数据限制、Network/Protect 资产清单、网络、WLAN 元数据以及防火墙规则/策略元数据。凭据、API 密钥、Cookie、授权标头和 WLAN 密码会在结构层面被排除。

# Optional absolute override; defaults to <UNIFI_DATA_DIR>/exports
UNIFI_EXPORT_DIR=/var/lib/unifi-mcp/exports

导出工具接受普通文件名，而非任意路径；会拒绝路径遍历和符号链接，并以 0600 权限原子写入文件。export_portable_snapshot 会附带 SHA-256 内容校验和；verify_snapshot 可检测格式错误、截断或已修改的快照。export_network_report 会将同一严格模型渲染为经过转义的独立 HTML，或公式安全的 CSV。

在验证控制器系列对应的端点和安全还原流程之前，原生控制器备份下载与还原会被明确报告为不可用。可移植快照用于评估和辅助重建，不会被描述为可还原的原生控制器备份。

历史记录和 Prometheus

启用运行时持久化后，capture_observations_now 会存储有界的站点整体健康状况、设备/客户端数量、流量总量和 Protect 摄像头健康状况。它绝不会存储单个客户端历史记录或数据包流遥测信息。query_observation_trends 会返回有界的 UTC 时间桶；对于漏采的数据，会标记为 present=false，而不会虚构插值结果。

Prometheus 支持不属于基础依赖集，默认不会启动监听器：

uv sync --extra observability
UNIFI_RUNTIME_ENABLED=true
UNIFI_PROMETHEUS_ENABLED=true
UNIFI_PROMETHEUS_HOST=127.0.0.1

指标使用固定名称，不包含控制器、站点、客户端、MAC、IP 或 SSID 标签。若要绑定到回环地址以外的地址，还必须设置 UNIFI_PROMETHEUS_ALLOW_REMOTE=true，并将 UNIFI_PROMETHEUS_BEARER_TOKEN_ENV 设置为包含 bearer token 的环境变量名称。每次收到请求时都会读取 token 值，且绝不会持久化。

客户端组织和 QoS 预览

启用运行时持久化后，客户端可以拥有多个本地标签，且最多只能属于一个本地分组。成员关系使用按控制器/站点限定的 SHA-256 值作为键，该值根据稳定的客户端 MAC 生成；不会存储原始 MAC 或可变的客户端名称。可以使用精确名称和主机名作为临时查找提示，但遇到匹配不明确的情况会拒绝操作，并要求提供确切的 MAC。客户端重命名后，标签和分组仍会保留，且不会更改控制器配置。

修改组织信息需要设置 confirm=true。使用 set_client_tags、create_client_group、assign_client_group、list_client_groups 和 list_clients_by_organization 管理或查询本地元数据。

plan_client_qos_policy 会持久化一个为期一小时的确定性目标快照，目标由单个客户端、标签或分组选定。目标账本仅包含按作用域限定的单向客户端键，并支持未来按目标恢复应用状态。本版本没有经过验证的控制器 QoS 适配器：get_client_qos_capabilities 会报告此限制，而 apply_client_qos_policy 会直接返回，不会修改控制器。本地标签不会自动关联任何 QoS 策略。

受信任的插件

除非在 UNIFI_PLUGIN_ALLOWLIST 中明确列出 Python 入口点名称，否则插件均处于禁用状态。插件会作为受信任的本地代码在服务进程中执行，且不会受到沙盒隔离。必需插件也必须列入允许列表，并在 UNIFI_PLUGIN_REQUIRED 中指定；缺失、不兼容、重复或加载失败的必需插件都会导致启动失败。可选插件的失败会被隔离，并可通过 get_plugin_status 查看。

插件使用 API 版本 1 和 unifi_mcp.plugins 入口点组：

[project.entry-points."unifi_mcp.plugins"]
example = "example_package.plugin:plugin"

加载的对象声明 api_version = 1，并实现 register(registry)。注册表支持使用明确的 read、write 或 admin 作用域注册工具，还支持具名收集器、JobDefinition 任务、通知接收器，以及返回字节的报告渲染器。插件名称不得与核心工具或任务重名。

Streamable HTTP 和 OIDC

Stdio 仍是默认的本地进程传输方式，无需配置身份提供方。仅当设置 UNIFI_TRANSPORT=streamable-http 时，才会启动远程 MCP；请使用 uv sync --extra oidc 安装声明的身份验证功能，并提供完整的 OIDC 设置：

UNIFI_TRANSPORT=streamable-http
UNIFI_HTTP_HOST=127.0.0.1
UNIFI_HTTP_PORT=8000
UNIFI_HTTP_PATH=/mcp
UNIFI_HTTP_PUBLIC_URL=https://mcp.example.com/mcp
UNIFI_OIDC_ISSUER=https://identity.example.com
UNIFI_OIDC_AUDIENCE=unifi-mcp
UNIFI_OIDC_ALGORITHMS=RS256

发现信息和 JWKS 数据通过 HTTPS 获取，使用有界超时时间，默认缓存五分钟；遇到未知签名密钥时会刷新一次。Token 会在本地验证允许的非对称算法、签名、颁发者、受众、有效期、主题和作用域。授权标头、Token、声明和签名密钥不会被记录或持久化。

所有 HTTP 工具调用都需要 UNIFI_OIDC_READ_SCOPE（默认值为 unifi:read）。修改操作还需要 UNIFI_OIDC_WRITE_SCOPE；运行时管理和插件状态查询需要 UNIFI_OIDC_ADMIN_SCOPE。现有的 confirm=true 门控仍然适用。绑定到回环地址以外的地址还需要设置 UNIFI_HTTP_ALLOW_REMOTE=true；在生产环境中，TLS 应在声明的 HTTPS 公共 URL 处终止。

多设备配置（推荐）

使用不同服务配置多个 UniFi 设备：

UNIFI_DEVICES='[
  {
    "name": "main-gateway",
    "url": "https://192.168.1.1",
    "api_key": "your-gateway-api-key",
    "services": ["network"],
    "site": "default"
  },
  {
    "name": "nvr",
    "url": "https://192.168.1.2",
    "api_key": "your-nvr-api-key",
    "services": ["network", "protect"],
    "site": "default"
  }
]'
UNIFI_VERIFY_SSL=false

设备配置字段：

字段	描述	默认值
name	用于指定设备的易记名称	（必填）
url	UniFi 设备的基础 URL	（必填）
api_key	来自 UniFi OS Control Plane 的 API 密钥	（必填）
services	数组：["network"]、["protect"] 或两者	["network"]
site	网络操作所用的站点名称	"default"
verify_ssl	验证 SSL 证书	false
username	Protect 事件的用户名（可选）	null
password	Protect 事件的密码（可选）	null

注意： username 和 password 字段仅用于 Protect 事件工具（移动事件、智能检测）。基本摄像头操作只需 API 密钥即可。

创建 API 密钥：

1. 登录 UniFi 控制器
2. 前往 Settings → Control Plane → API
3. 创建具有相应权限的新 API 密钥

旧版单设备配置

为保持向后兼容，仍支持单设备配置：

UNIFI_MODE=local_api_key
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_CLOUD_API_KEY=your-api-key
UNIFI_SITE=default
UNIFI_VERIFY_SSL=false

本地会话身份验证（传统方式）

如需通过用户名/密码身份验证获取完整功能：

UNIFI_MODE=local
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_USERNAME=local-admin
UNIFI_PASSWORD=your-password
UNIFI_SITE=default
UNIFI_IS_UDM=true
UNIFI_VERIFY_SSL=false

Cloud API（api.ui.com）

用于访问 Ubiquiti Cloud API：

UNIFI_MODE=cloud
UNIFI_CLOUD_API_KEY=your-api-key

在 unifi.ui.com → API 部分获取 API 密钥。

与 Claude Desktop 搭配使用

添加到 Claude Desktop 配置中（Linux 上为 ~/.config/claude/claude_desktop_config.json，macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "unifi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/unifi-mcp", "python", "-m", "unifi_mcp.server"],
      "env": {
        "UNIFI_DEVICES": "[{\"name\":\"gateway\",\"url\":\"https://192.168.1.1\",\"api_key\":\"your-key\",\"services\":[\"network\"]},{\"name\":\"nvr\",\"url\":\"https://192.168.1.2\",\"api_key\":\"your-key\",\"services\":[\"network\",\"protect\"]}]",
        "UNIFI_VERIFY_SSL": "false"
      }
    }
  }
}

与 Claude Code / opencode 搭配使用

# Add the MCP server
claude mcp add unifi -- uv run --directory /path/to/unifi-mcp python -m unifi_mcp.server

或者在 opencode.json 中：

{
  "mcp": {
    "unifi": {
      "type": "local",
      "command": ["/path/to/unifi-mcp/.venv/bin/python", "-m", "unifi_mcp.server"],
      "enabled": true
    }
  }
}

可用工具

服务端运行状况

• get_server_health - 报告服务端版本、stdio 传输方式、已配置服务数量，以及可选的持久化状态。响应会有意省略凭据、控制器地址、设备名称和数据库路径。

多设备管理

• list_unifi_devices - 列出所有已配置的 UniFi 设备及其服务

设备管理

• list_devices - 列出所有 UniFi 网络设备
• get_device_details - 获取设备详细信息
• restart_device - 重启设备
• locate_device - 闪烁 LED 以定位设备
• get_device_stats - 获取性能统计信息
• upgrade_device - 升级固件
• provision_device - 强制重新配置
• get_device_ports - 列出交换机/网关端口配置和链路状态
• set_device_port - 配置一个端口；需要 confirm=true，并验证控制器回读结果

客户端管理

• list_clients - 列出已连接的客户端
• list_all_clients - 列出所有已知客户端（包括离线客户端）
• get_client_details - 获取客户端详细信息
• block_client / unblock_client - 阻止/解除阻止客户端
• kick_client - 断开客户端连接
• forget_client - 从已知客户端中移除
• get_client_traffic - 获取流量统计信息
• reserve_client_ip - 通过 DHCP 预留为客户端预留 IP
• get_client_organization / set_client_tags - 读取或替换本地持久化标签
• create_client_group / delete_client_group - 管理仅限本地的分组
• assign_client_group / list_client_groups - 管理和查看单个分组成员关系
• list_clients_by_organization - 解析确定性的标签或分组目标集
• get_client_qos_capabilities - 报告经过验证的控制器 QoS 支持情况
• plan_client_qos_policy / apply_client_qos_policy - 预览 QoS 目标；仅在存在经过验证的适配器时应用

站点管理

• list_sites - 列出所有站点
• get_site_health - 获取站点健康状态
• get_site_settings - 获取站点设置
• get_sysinfo - 获取系统信息
• get_networks - 获取网络／VLAN 配置
• get_wlans - 获取无线网络配置
• get_port_profiles - 获取交换机端口配置文件
• get_firewall_rules - 获取旧版防火墙规则
• get_firewall_policies - 获取基于区域的防火墙策略（UniFi Network 9+）
• get_routing_table - 获取路由表
• get_port_forwards - 获取端口转发规则
• create_port_forward / delete_port_forward - 管理端口转发

配置管理（写入）

• create_network / update_network / delete_network - 管理网络和 VLAN；每项操作都需要 confirm=true，并验证控制器回读结果
• create_wlan / update_wlan / delete_wlan - 管理无线网络
• create_firewall_policy / set_firewall_policy_enabled / delete_firewall_policy - 管理基于区域的防火墙策略
• export_camera_clip - 在 UNIFI_EXPORT_DIR 下导出 MP4；需要 confirm=true
• get_all_sites_health - 查看所有站点的健康状况概览

会删除数据或造成中断的写入工具均需确认，或通过 MCP 注解标记为具有破坏性。

统计与监控

• get_network_health - 网络整体健康状况
• get_recent_events - 最近事件
• get_alarms - 活动警报
• archive_all_alarms - 归档所有警报
• run_speed_test - 开始速度测试
• get_speed_test_status - 获取速度测试结果
• get_dpi_stats - DPI 统计信息
• get_traffic_summary - 流量摘要

AI 洞察工具

• analyze_network_issues - 全面分析问题
• get_optimization_recommendations - 配置建议
• get_client_experience_report - 客户端质量指标
• get_device_health_summary - 设备健康状况概览
• get_traffic_analysis - 流量模式分析
• get_all_sites_health - 查看所有站点的健康状况概览

多站点编排

• get_global_inventory - 汇总所有控制器的统一设备清单
• get_global_health - 汇总所有控制器的健康报告
• get_global_client_summary - 汇总所有控制器的客户端数量、流量最高的客户端和被阻止的客户端
• troubleshoot_client - 深入排查客户端问题

UniFi Protect

• list_cameras - 列出所有摄像头及其连接状态
• get_camera_details - 获取摄像头详细信息
• get_camera_snapshot - 获取实时快照（base64 JPEG）
• get_protect_system_info - 获取 NVR 系统信息
• get_camera_health_summary - 查看摄像头健康状况概览及问题
• get_liveviews - 获取已配置的实时视图布局
• get_protect_accessories - 列出灯具、传感器、蜂鸣器和查看器

UniFi Protect 事件（需要用户名／密码）

• get_motion_events - 获取最近的运动事件
• get_smart_detections - 获取智能检测事件（人物、车辆、动物、包裹）
• get_protect_event_summary - 按类型汇总所有事件
• get_recent_protect_activity - 快速查看近期活动概况

对话示例

连接 MCP 服务后，你可以向 Claude 提问：

网络管理

• “列出我的所有 UniFi 设备”
• “当前网络的健康状况如何？”
• “分析我的网络，找出存在的问题”
• “你有什么优化建议？”
• “显示客户端体验指标”
• “排查 MAC 地址为 aa:bb:cc:dd:ee:ff 的客户端”
• “哪些客户端占用了最多带宽？”
• “有没有设备需要更新固件？”
• “显示最近的网络事件”
• “运行速度测试”

UniFi Protect

• “列出我的所有摄像头”
• “显示摄像头健康状况概览”
• “获取前门摄像头的快照”
• “我的 NVR 状态如何？”
• “有没有摄像头已断开连接？”
• “显示 Protect 配件”

Protect 事件（需要凭据）

• “显示最近的动作事件”
• “过去 24 小时内发生了哪些智能检测事件？”
• “今天检测到过人物吗？”
• “总结过去一周的事件”
• “显示前门摄像头的近期活动”

多设备

• “列出我已配置的 UniFi 设备”
• “显示我的 NVR 上的摄像头”
• “获取主网关的网络运行状况”

开发

运行测试

uv run pytest

代码格式化

uv run ruff check .
uv run ruff format .

Docker

docker build -t unifi-mcp .
docker run -i --rm --env-file .env unifi-mcp

若要启用可选的运行时持久化，请在镜像的可写 /data 目录上挂载一个命名卷：

docker run -i --rm \
  --env-file .env \
  --env UNIFI_RUNTIME_ENABLED=true \
  --env UNIFI_DATA_DIR=/data \
  --volume unifi-mcp-data:/data \
  unifi-mcp

--rm 会移除已停止的容器，但 unifi-mcp-data 命名卷会保留，并为后续运行保存 /data/runtime.db。

请求新功能

• 新增技能：提交 issue，并使用 [Skill] 前缀——描述问题、工作流和预期输出
• 修改技能：提交 issue，并使用 [Skill: skill-name] 前缀——说明缺少或损坏的内容
• 新增工具：提交 issue，并使用 [Tool] 前缀——注明 UniFi API 端点和预期格式

详细的贡献指南请参阅 SKILLS.md。

发布历史请参阅 CHANGELOG.md，参与贡献请参阅 CONTRIBUTING.md。

安全说明

• 凭据通过环境变量传递——切勿提交 .env
• 默认禁用 TLS 验证（UNIFI_VERIFY_SSL=false），因为此服务旨在受信任的局域网中运行，并通过 IP 连接到使用自签名证书的 UniFi 控制台。仅在使用受 CA 信任的证书时启用验证。
• 通过 stdio（本地 IPC）通信时，无需身份验证——传输层被视为受信任的本地进程。通过 Streamable HTTP 通信时，所有工具调用都需要有效的 OIDC 令牌，并具备相应的读、写或管理员权限范围；这些要求由服务端强制执行。
• 此服务提供读写工具
• 对于已实现的破坏性操作或可能造成中断的工具，会添加注释和/或明确要求确认；MCP 客户端决定如何呈现或遵循这些注释
• 不提供恢复出厂设置等特别危险的操作
• API 密钥应妥善保管并定期轮换

许可证

MIT 许可证

贡献

欢迎贡献！请提交 issue 或拉取请求。