UniFi Network MCP

UniFi Network MCP Server

为 AI 助手和其他兼容 MCP 的客户端提供 210 个 UniFi Network Controller 工具的 MCP 服务。可查询客户端、设备、防火墙规则、VLAN、VPN、Traffic Flows、统计信息等，并采用默认安全的权限设置，所有变更操作都需先预览再确认。

当现有 AI 助手或其他兼容 MCP 的客户端需要使用 UniFi Network 工具时，请使用此服务。通过 HTTP 集成的软件（包括自动化服务、代码执行运行时和 MCP 适配器）应使用 unifi-api-server 进行 REST 和 GraphQL 读取、操作及 SSE 事件处理。调用应用必须对生成的代码进行沙箱隔离并强制执行资源限制。

安装

Claude Code（推荐）

此插件会安装 MCP 服务、用于发现工具的 Agent 技能，以及引导式设置命令：

/plugin marketplace add sirkirby/unifi-mcp
/plugin install unifi-network@unifi-plugins

然后运行交互式设置，配置控制器连接：

/unifi-network:unifi-network-setup

此流程会引导你输入控制器主机、凭据和权限偏好。凭据通过文件或命令提供程序传入，绝不会在聊天中输入。设置结果会保存为插件的 Claude Code 选项，并在所有项目中生效；作为选项输入的密码或 API 密钥会存储在系统钥匙串中。设置完成后，请启动新的 Claude Code 会话以连接。

如果你使用的插件版本早于 1.0.0，且设置保存在项目的 .claude/settings.local.json 中，请参阅插件升级指南。

Codex

注册市场，然后通过 Codex 的 /plugins 界面安装 unifi-network：

codex plugin marketplace add sirkirby/unifi-mcp

安装后，让 Codex 使用 UniFi Network 设置技能。设置会将带版本固定的 MCP 服务条目及控制器设置保存到 Codex 的 config.toml 中，并提示你重启 Codex。每次升级插件后，都要使用 --refresh 重新运行设置。

PyPI / Docker

# PyPI
uvx unifi-network-mcp@latest
# or: pip install unifi-network-mcp

# Docker
docker pull ghcr.io/sirkirby/unifi-network-mcp:latest

# From source
git clone https://github.com/sirkirby/unifi-mcp.git
cd unifi-mcp && uv sync

使用示例

关于下一次次要版本发布中已批准的 MAC 参数重命名（会造成不兼容变更），请参阅 MAC 参数迁移指南。

连接后，只需用自然语言向你的 AI Agent 提问：

“显示 Guest VLAN 上所有客户端的信号强度和数据用量。”

“创建一条防火墙规则，在午夜到早上 6 点之间阻止 IoT 设备访问互联网。”

“本周哪些接入点的客户端断连次数最多？”

“审查我的防火墙策略——是否存在冗余或冲突规则？”

“将 192.168.1.45 上的设备重命名为 ‘Living Room TV’，并显示其流量统计。”

“我的网络在过去 24 小时内有哪些变化？显示新客户端和配置变更。”

“显示过去一小时内流量最大的会话，并总结各方之间的通信情况。”

所有变更操作（防火墙规则、设备变更、客户端封锁）都采用先预览、再确认的流程——在应用任何变更之前，你都可以确切看到将要发生的变化。

V2 NAT 规则

unifi_list_nat_rules 和 unifi_get_nat_rule 用于读取 V2 NAT 规则。创建、更新、删除和切换工具需要 Network 会话凭据，并使用 V2 NAT 规则 ID；端口转发和 Integration API 的 ID 与之不同。公开的写入操作支持 DNAT、SNAT 和 MASQUERADE，适用于 IPv4、tcp_udp 或 all，以及 NONE 或 ADDRESS_AND_PORT 过滤器。创建的规则默认 enabled=false。 创建的规则会标记为手动且非预定义，并在读取时检查这两个值。对于来源缺失或非手动的现有规则，无法通过这些工具进行编辑。 带有转换后 port 的 SNAT 规则需要 source_filter.port；控制器会验证端口是否对应。对于缺少该源端口的现有规则，必须在同一次更新中补齐后，才能通过这些工具编辑。 切换操作需要显式指定 enabled 布尔值，因此重复发送相同请求不会产生操作。公开写入尚未验证 IPv6、PPPoE、反向／排除匹配以及其他过滤器变体。 如果已存储规则的类型未经验证，即使同一请求将其类型改为已验证类型，也会拒绝对选择器的编辑。

MCP 更新预览会显示基于最新状态合并生成的前后对比。确认时会再次读取最新状态，最多发送一次完整替换，然后检查是否持久化；删除操作会检查规则是否确实不存在。如果控制器回复或回读结果不确定，请先列出规则再重试。由于 V2 NAT 不支持条件替换，因此在获取状态和 PUT 之间发生的控制器并发编辑可能会被覆盖。这些检查只能证明存储的配置，不能证明数据包层面的执行效果。现有 Core NAT 方法会保留原有返回结构；控制器变更异常现在会提供安全且固定的指引，而不再包含原始响应文本。

如需进行获批的数据包测试，请使用 IPv4 DNS 重定向方案。该方案涵盖单个客户端和合成目标，包括同子网返回流量和清理步骤。

配置

在服务器的进程环境中设置这些变量。插件设置技能已为 Codex 和 OpenClaw 完成此操作；在 Claude Code 中，插件会将其选项映射到这些变量。服务器不会自动加载 .env 或工作目录中的 YAML 文件；请在启动器中显式加载可信的环境文件（支持 Docker env_file:），或者通过绝对路径 CONFIG_PATH 指定自定义 YAML。迁移示例请参阅配置。

未配置控制器主机时，服务器仍会以设置模式启动：它会告知客户端如何进行配置，只提供只读的 unifi_setup_status 工具，并且不会连接控制器。

# Server-specific variables (recommended)
UNIFI_NETWORK_HOST=192.168.1.1      # Controller IP or hostname
UNIFI_NETWORK_USERNAME=admin         # Local admin username
UNIFI_NETWORK_PASSWORD=your-password # Admin password
# Optional:
# UNIFI_NETWORK_API_KEY=             # UniFi API key (inventory and explicit Integration API tools)
# UNIFI_NETWORK_PORT=443             # Controller HTTPS port
# UNIFI_NETWORK_SITE=default         # UniFi site name
# UNIFI_NETWORK_VERIFY_SSL=false     # SSL certificate verification
# UNIFI_NETWORK_WEBSOCKET_ENABLED=true   # Real-time event listener feeding unifi_recent_events
# UNIFI_NETWORK_EVENT_BUFFER_SIZE=100    # Positive ring buffer capacity; invalid values prevent startup
# UNIFI_NETWORK_EVENT_BUFFER_TTL=300     # Positive lifetime in seconds; invalid values prevent startup

**回退：**现有的 UNIFI_* 变量（例如 UNIFI_HOST）仍可使用。服务器会优先检查 UNIFI_NETWORK_*；如果未设置服务器专用变量，则回退到 UNIFI_*。对于单控制器设置，只需使用共享变量即可。

API 密钥清单与会话身份验证

配置 UNIFI_NETWORK_API_KEY，即可在不使用用户名/密码的情况下获取设备、 活动客户端、网络和 WLAN 列表。相同的工具会选择可用的读取路径；无需重复 创建 API 密钥工具。如果也配置了有效的会话凭据，则仍优先使用现有会话路径。

对于接受在旧版清单端点上使用 API 密钥的控制器，会保留常用 ID 和字段。已在 使用 UniFi OS 代理的 Network 10.6.106 上验证；尚未确定最低支持固件版本。 其他控制器可以使用公开的 Integration 清单回退路径（前提是该 API 可用）。 公开清单的字段和网络覆盖范围较窄（例如，可能不包含 WAN/VPN 网络）。结果会 标明 source_api=integration，并将公开 UUID 作为 integration_id 提供，而 不会将其作为旧版资源 ID。请勿将这些 UUID 传递给旧版详情/更新工具。缺失的 旧版字段表示未知。因此，API GraphQL 投影会将不可用的 enabled、wired 和 guest 标记设为 null；客户端必须处理这些 null 值。

历史客户端（include_offline=true）、完整详情、旧版变更操作以及 Network websocket 仍要求使用其支持的旧版/会话路径。API 密钥旧版传输仅限于已验证的 清单 GET 请求；读取成功并不代表有权写入。显式 Integration 工具（如 DPI 查询和防火墙排序）保留各自的 API 密钥约定（解析旧版区域 ID 也需要会话）。 Protect 仍需要会话引导；对于公开 setter，还需要额外的 API 密钥。Access 保留 独立的 API 令牌和代理会话路径。发现功能会报告 local_only、api_key_only、 either 或 both；这些值表示要求，并不代表已配置的凭据已成功通过身份验证。

MCP 响应大小

对于已提供结构化输出的工具结果，默认响应模式为 adaptive。它会根据 MCP 初始化期间声明的规范日期格式 protocolVersion 对每个请求进行分类，而不是 根据客户端的产品名称或应用版本进行分类。声明 MCP 2025-06-18 或更高版本的 请求会收到简洁的 content，并在 structuredContent 中完整返回一次结果；声明 较早版本（如 2024-11-05 或 2025-03-26）的请求，或版本元数据缺失或格式错误 的请求，会在 content 中保留完整的兼容性 JSON。将 UNIFI_NETWORK_MCP_CONTENT_MODE 设为 compat 可强制使用重复的兼容格式；设为 compact 可在协商请求之外强制 使用简洁文本和完整结构化输出。此服务专属变量优先于 UNIFI_MCP_CONTENT_MODE； 对于任何只从 content 获取完整结果的客户端，无论其声明的版本如何，都请使用 compat。

惰性加载元工具（*_tool_index、*_execute、*_batch、*_batch_status 和仅 用于惰性加载的 *_load_tools）仍然只有 content；它们不属于上文所述的 2025-06-18 之前的协议类别。对于结构化的内部结果，*_execute 和 *_batch_status 会在 content 中提供一个规范化的 JSON 负载，而不是嵌套的传输 对；只有 content 的执行结果保持不变。响应模式不会将这些元工具转换为 structuredContent。

默认情况下，Network 还会限制两个较大的源响应：unifi_get_dashboard 使用 summary=true，而 unifi_list_rogue_aps 返回最多包含 100 条记录的摘要页面。 传入 summary=false 可请求所选仪表板或恶意 AP 数据的完整内容。

敏感响应字段

默认情况下，网络工具会在向 MCP 客户端返回数据前，隐去已知包含机密信息的字段。这包括 WLAN 密码短语、VPN 密钥材料、完整的 VPN 配置块、SNMP 团体字符串、SNMPv3 密码，以及原始/详细响应和变更预览中的设备 SSH 凭据与管理密钥。需要原始值时，可通过 UNIFI_NETWORK_REDACT_SENSITIVE_FIELDS=false 或全局 UNIFI_REDACT_SENSITIVE_FIELDS=false 策略标志，为受信任的本地管理进程关闭隐去功能。

已确认的 Network/WLAN 和 VPN 状态写入会从控制器重新读取，并报告精确的 persisted_fields、unchanged_fields、dropped_fields 和 coerced_fields。已满足条件的无操作字段会列在 unchanged_fields 下，不会导致失败的写入被视为部分成功。若响应包含 success: false 和 mutation_applied: true，表示控制器已接受变更，但未完全按原样持久化；这可能是部分写入，而非回滚。重试或应用补偿性更改前，请检查 partial_success 和 details_after_attempt。

unifi_update_vpn_server_alternate_address 使用 server_id、部分 update_data 对象和 confirm（默认为 false）更新 WireGuard 服务端公布的地址。可接受的字段为 alternate_address_enabled（布尔值）和 alternate_address（主机名或 IPv4 地址，不含 URI、端口或路径）。启用时，合并后的配置中必须包含有效地址。禁用时，除非同时提供替换地址，否则会保留已存储的地址。空值和未知字段会被拒绝。服务端读取结果会使用相同的字段名；对于控制器中不存在的值，显示为 null。

此操作需要 Network 会话凭据，并受 VPN_SERVERS UPDATE 策略门控。MCP 预览会显示最新的变更前后值；API 操作预览仅显示提交的参数，执行时才会验证有效状态。确认更新会再次获取完整记录、保留无关字段，并在写入后验证请求的字段。完整记录 PUT 仍可能与并发编辑发生竞争。如果传输或回读结果不确定，则返回 mutation_applied: null；重试前请检查服务端。预览和结果仅包含两个公开的备用地址字段。其他 VPN 服务端类型不在此经验证的写入范围内。

运行

# stdio transport (default — for Claude Desktop, LM Studio, etc.)
unifi-network-mcp

# Docker
docker run -i --rm \
  -e UNIFI_NETWORK_HOST=192.168.1.1 \
  -e UNIFI_NETWORK_USERNAME=admin \
  -e UNIFI_NETWORK_PASSWORD=secret \
  ghcr.io/sirkirby/unifi-network-mcp:latest

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "unifi": {
      "command": "uvx",
      "args": ["unifi-network-mcp"],
      "env": {
        "UNIFI_NETWORK_HOST": "192.168.1.1",
        "UNIFI_NETWORK_USERNAME": "admin",
        "UNIFI_NETWORK_PASSWORD": "your-password"
      }
    }
  }
}

Agent 技能

通过 Claude Code 安装时，网络插件会附带三项 Agent 技能，为 Claude 扩展专用的网络管理工作流。

网络健康检查

触发词：“检查网络健康状况”、“哪里出了问题”、“运行健康检查”、“网络状态”

通过一次 unifi_batch 调用收集完整的诊断快照，包括系统信息、网络健康状况、设备列表和活动警报，然后生成结构化的健康报告。报告还包含设备状态代码、警报类型与严重级别，以及健康子系统诊断（WAN → LAN → WLAN → VPN 优先级顺序）的参考文档。

防火墙管理器

触发词：“阻止流量”“创建防火墙规则”“设置 IoT 隔离”“管理内容过滤”

通过安全的“预览后确认”工作流，以自然语言管理防火墙。包含：

• 常见场景的策略模板（references/policy-templates.yaml）：

  模板	说明
  iot-isolation	阻止 IoT VLAN 访问主 LAN
  guest-lockdown	将访客网络限制为仅可访问互联网
  kids-content-filter	通过 DPI 按时间段屏蔽社交媒体和游戏
  block-bittorrent	通过 DPI 阻止 P2P/BitTorrent 流量
  work-vpn-split-tunnel	允许企业 VPN，同时保持本地 LAN 可访问
  camera-isolation	限制 IP 摄像头，使其只能与 NVR 通信

• 快照/差异对比工作流 — Claude 会在每次变更前保存包含所有策略、区域和组的带时间戳 JSON 快照，然后将变更后的状态与之对比，立即发现意外变更

• 参考文档，涵盖防火墙架构、DPI 类别和完整的模板参数列表

防火墙审计器

触发词：“审计防火墙”“检查防火墙规则”“检查安全问题”“为我的防火墙评分”

针对 4 个类别中的 16 项安全基准进行全面自动审计，生成 0–100 分的评分，并为每项发现提供修复指导。Claude 会分派 MCP 工具调用，并根据 references/security-benchmarks.md 评估每项基准；一个小型 CLI（scripts/unifi-firewall-score）会将审计发现转换为规范且版本稳定的评分，从而确保审计历史具有可比性。

评分阈值：

评分	等级	含义
80–100	良好	符合最佳实践，仅有少量不足
60–79	需要关注	存在明显不足；应按计划安排修复
0–59	严重	存在重大风险，需立即修复

基准类别（4 × 25 分）：

• 网络分段（SEG-01–04）— IoT/访客/管理 VLAN 隔离、明确的 VLAN 间策略
• 出口控制（EGR-01–03）— 对高风险 VLAN 进行出站过滤、DNS 强制执行、威胁情报拦截
• 规则整洁度（HYG-01–05）— 冲突、冗余/已禁用规则、过期引用、命名、规则遮蔽
• 拓扑（TOP-01–04）— 离线设备、固件更新状态、交换机上联端口间的 VLAN 一致性、孤立的端口配置文件

每项发现都包含基准 ID、严重程度（严重/警告/信息性）、通俗易懂的说明，以及在可自动化时用于修复的确切 MCP 工具调用。审计历史记录在 audit-history.json 中，以便查看评分随时间的变化趋势。

---

工具改进

设备分类（unifi_list_devices）

unifi_list_devices 现在会返回 device_category 字段，正确分类每台已接入管理的设备：

类别	设备
ap	真正的接入点（不包括通过无线网状网络连接的 USP Smart Power 插排）
switch	受管交换机
gateway	安全网关和 Dream Machines
pdu	配电单元
wan	UCI 有线互联网设备
unknown	无法识别的设备类型

ap 类别以控制器的 is_access_point 布尔标志作为权威依据，而不只是根据设备类型前缀判断。这意味着 USP Smart Power 插排（其设备类型显示为 uap）会被正确排除在 AP 类别之外。

丰富的设备字段

每条设备记录现在除现有的 MAC、名称、型号、IP、固件、运行时间和状态外，还包含以下字段：

字段	类型	描述
device_category	string	语义类别：ap、switch、gateway、pdu、wan、unknown
upgradable	bool	是否有可用的固件升级
connection_network	string	设备管理接口所在 VLAN 的名称
uplink	object	拓扑信息：上行链路类型、速度、父设备名称和端口
load_avg_1	float	1 分钟负载平均值（来自设备系统统计数据）
mem_pct	float	内存利用率百分比（0–100）
model_eol	bool	设备型号是否已达到生命周期终止状态

---

文档

• 配置 — 完整的环境变量参考、YAML 配置、控制器类型检测
• 权限 — 权限系统、类别默认设置、如何启用高风险工具
• 工具目录 — 按类别整理的全部 210 个工具
• 传输方式 — stdio、Streamable HTTP 和 SSE 设置
• 故障排除和支持包 — 经审核的支持证据、连接问题、SSL、缺失的工具

开发

cd apps/network
make test         # Run tests
make lint         # Lint
make format       # Format
make manifest     # Regenerate tools_manifest.json
make pre-commit   # All of the above

完整的单体仓库工作流请参阅根目录下的 CONTRIBUTING.md。

许可证

MIT