Unifi MCP Server

UniFi MCP 服务

通过模型上下文协议实现 UniFi 网络的 AI 原生控制

一个 MCP 服务，将 UniFi Network、UniFi Protect 和 UniFi 云 API（Site Manager、Mobility、InnerSpace、Carrier Fabric）作为 MCP 工具开放，让 AI Agent 能通过一个标准接口读取和更改 UniFi 基础设施。它既可以连接单个控制器，也可以在集群模式下连接多个控制器。

当前版本：0.6.4。 请参阅 CHANGELOG.md 了解变更内容。

目录

• 功能
• API 模式
• 快速开始
• Agent 技能
• 工具配置和安全控制
• 网络传输和部署
• 通过代码调用服务
• 原生 MCP 提示词
• 文档
• 开发

功能

本地模式下提供来自 60 个模块的 343 个工具。

• 网络： 客户端（搜索、屏蔽、重新连接）、网络和 VLAN、WiFi SSID、DHCP 保留、DNS、WAN、访客凭证、QoS 配置文件和流量路由、DPI 统计信息、流量流。
• 设备： 清单、接入、重启、定位、升级、无线电设置、端口配置文件和逐端口覆盖设置、交换和堆叠、拓扑导出（JSON、GraphML、DOT）、诊断、WiFi 信道规划。
• 安全： 旧版防火墙规则和组、基于区域的防火墙（区域、策略、区域矩阵）、ACL 规则、流量匹配列表、端口转发、VPN 和站点到站点 VPN、内容过滤、RADIUS 和访客门户。
• Protect： 摄像头、NVR、视图、事件、传感器、灯、门铃、警报器、继电器、扬声器、警报中枢和警报管理器。
• 云： Site Manager（主机、站点、跨站点统计信息）、连接器代理、Mobility 工作区和设备、InnerSpace 楼层平面图和清单、Carrier Fabric 订阅者和服务计划。
• 运维： 站点、备份（创建、计划、下载、恢复）、事件、多站点聚合、站点间设备迁移。
• 机群模式（可选，需 Postgres 和 Redis）：通过一个服务管理多个控制器，提供带加密凭据的控制器注册表、由服务颁发且带角色的令牌、共享读取缓存、多个副本和后台工作进程，以及可跨控制器读取的 fleet_* 工具。参见 MULTI_CONTROLLER.md 和 docs/FLEET_SCALING_PLAN.md。
• 原生提示词： 八种参数化的 UniFi 运维工作流（运行状况检查、客户端连接、WiFi 性能、设备调查、防火墙审查、变更规划、Protect 运行状况、机群摘要），通过标准的 prompts/list 和 prompts/get 操作提供。参见 docs/PROMPTS.md。
• 安全性： 每个会修改数据的工具都需要 confirm=True，并支持 dry_run=True；此外还提供只读和试运行服务模式、按风险级别进行基于角色的访问控制，以及哈希链审计日志（参见下文）。
• A2A 发现与委派： 基于实时工具注册表生成的 Agent 卡片，发布于 /a2a/agent-card 和 /.well-known/agent-card.json；另提供能力清单和委派端点，可在服务自身的角色、确认和审计控制下运行已注册的工具。参见 A2A.md。
• 可观测性： Prometheus /metrics、/healthz、审计记录的 SIEM 导出、可选的 Redis 缓存、带 HMAC 验证的 Webhook。

API 模式

设置 UNIFI_API_TYPE，以选择服务访问 UniFi 的方式。

模式	访问目标	用途
local（推荐）	您局域网中的 UniFi 控制台或网关（UNIFI_LOCAL_HOST）	所有功能：设备和客户端控制、配置、防火墙、Protect
cloud-ea	UniFi 的 Early Access 云 API	站点和汇总统计信息；不支持逐设备控制或配置
cloud-v1	UniFi 的稳定版 v1 云 API	站点和汇总统计信息；不支持逐设备控制或配置

云工具（Site Manager、Mobility、InnerSpace、Carrier Fabric）会调用 api.ui.com，并在所有模式下注册。设置 UNIFI_SITE_MANAGER_ENABLED=true 即可使用这些工具。在 local 模式下，服务会注册 343 个工具；在任一云模式下会注册 71 个工具。

基于区域的防火墙工具需要 UniFi Network 9.0 或更高版本。部分文档中提到的 UniFi 端点并非所有固件版本都支持；参见 docs/UNIFI_API.md。

快速开始

1. 获取 API 密钥

1. 登录 UniFi Site Manager。
2. 前往 Settings → Control Plane → Integrations，然后选择 Create API Key。
3. 复制密钥。它只会显示一次。

2. 安装

pip install unifi-mcp-server          # or: uv tool install unifi-mcp-server
# Fleet mode extras (Postgres, Redis):
pip install 'unifi-mcp-server[fleet]'

或者使用容器镜像（amd64、arm64 和 arm/v7；-fleet 变体适用于 amd64 和 arm64）：

docker pull ghcr.io/enuno/unifi-mcp-server:latest

3. 将其添加到 MCP 客户端

Claude Desktop（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上的 %APPDATA%\Claude\claude_desktop_config.json）、Cursor（通过 View: Open MCP Settings 打开的 mcp.json）以及大多数其他 MCP 客户端，都使用相同的 mcpServers 配置块：

{
  "mcpServers": {
    "unifi": {
      "command": "uvx",
      "args": ["unifi-mcp-server"],
      "env": {
        "UNIFI_API_KEY": "<your-api-key>",
        "UNIFI_API_TYPE": "local",
        "UNIFI_LOCAL_HOST": "192.168.2.1"
      }
    }
  }
}

如果通过 pip 安装，请使用 "command": "unifi-mcp-server" 并删除 args。若要运行容器：

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "UNIFI_API_KEY=your-api-key-here",
        "-e", "UNIFI_API_TYPE=local",
        "-e", "UNIFI_LOCAL_HOST=192.168.2.1",
        "ghcr.io/enuno/unifi-mcp-server:latest"
      ]
    }
  }
}

保留 -i，不要添加 -d：客户端通过容器的 stdin 和 stdout 与服务通信。

4. 主要设置

变量	用途	默认值
UNIFI_API_KEY	UniFi API 密钥（必填）	—
UNIFI_API_TYPE	local、cloud-ea 或 cloud-v1	cloud-ea
UNIFI_LOCAL_HOST / UNIFI_LOCAL_PORT	local 模式下的控制台地址	— / 443
UNIFI_LOCAL_VERIFY_SSL	验证控制台的 TLS 证书。设为 false 时，启动时会记录警告	true
UNIFI_LOCAL_CA_FILE	自签名控制台的 CA 证书（PEM），可用于替代关闭验证	—
UNIFI_DEFAULT_SITE	工具调用未指定站点时使用的站点	default
UNIFI_SITE_MANAGER_ENABLED	启用云端工具（Site Manager、Mobility、InnerSpace、Carrier）	false
UNIFI_PROFILE	仅注册一组工具（配置组）	all
UNIFI_READ_ONLY / UNIFI_DRY_RUN	只读或仅预览模式的服务	false
DEBUG	注册 debug_api_request（原始 GET/DELETE、破坏性级别，只读模式下会移除）。生产环境中请勿设置	unset
MCP_SERVER_TRANSPORT	stdio、streamable_http、http 或 sse	stdio
MCP_AUTH_TOKEN	Bearer 令牌；网络传输必填；viewer:<token>（或 operator:、admin:）可限制令牌角色	—
REDIS_URL	可选的响应缓存	—
WEBHOOK_SECRET	接收 UniFi Webhook 的 HMAC 密钥	—
DATABASE_URL	启用机群模式（Postgres）	—

.env.example 列出了所有设置及其注释，包括审计日志记录、SIEM 导出、指标、Supermemory 和 agnost.ai。

Agent 技能

skills/ 目录中包含 Agent 技能：AI Agent 可按需加载的 Markdown 文件，用于了解有哪些 UniFi 工具，以及如何安全地使用这些工具，而无需将每个工具定义都保留在上下文中。每项技能都是一个包含 SKILL.md 的文件夹，采用 Claude Code 和其他 Agent 使用的安装布局。

使用服务（运维技能）

技能	涵盖内容
unifi-network	客户端、网络和 VLAN、WiFi、DHCP、DNS、WAN、兑换券
unifi-devices	清单、采用、重启和升级、端口、交换、拓扑
unifi-security	防火墙规则和分组、基于区域的防火墙、ACL、端口转发、VPN
unifi-system	站点、备份、QoS、流量流、DPI、RADIUS、访客门户
unifi-channel-planning	基于邻居扫描的低干扰 WiFi 信道规划

修改此代码库（开发者技能）

技能	涵盖内容
unifi-mcp-tool-builder	添加任意 MCP 工具：模型、函数、注册、测试、文档
unifi-network-config-tools	网络配置工具：URL 空间、站点 ID、读取-修改-写入
unifi-security-tools	防火墙、ZBF、ACL 和端口转发工具及其风险级别
unifi-protect-tools	protect_* 模块和 Protect 客户端
unifi-cloud-fleet-tools	云 API 工具和机群技术栈

安装

Claude Code 从 ~/.claude/skills/<name>/SKILL.md（每个会话）或 <project>/.claude/skills/<name>/SKILL.md（单个项目）加载技能。复制所需的文件夹：

git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server
mkdir -p ~/.claude/skills

# All operator skills
cp -r skills/unifi-network skills/unifi-devices skills/unifi-security \
      skills/unifi-system skills/unifi-channel-planning ~/.claude/skills/

# Or one skill
cp -r skills/unifi-security ~/.claude/skills/

# The one-file overview of the whole server, as a skill named "unifi"
mkdir -p ~/.claude/skills/unifi && cp SKILL.md ~/.claude/skills/unifi/SKILL.md

其他读取相同 SKILL.md 格式的 Agent 也使用相同的文件夹；将它们复制到对应 Agent 的技能目录中（例如，Codex 会读取 .agents/skills/）。若要更新，请重新拉取并复制。在此仓库中，开发者技能已安装到 Claude Code（.claude/skills/）和 Codex（.agents/skills/）中。

使用

你无需自行调用技能。Agent 会读取各技能的描述，加载与你的请求相匹配的技能，然后调用该技能所说明的 MCP 工具，因此 MCP 服务也必须配置在同一个客户端中。例如：

• “当前访客 VLAN 上有哪些客户端？”会加载 unifi-network。
• “检查基于区域的防火墙，找出任何允许 WAN 访问 LAN 的规则。”会加载 unifi-security。
• “哪些 AP 与邻近 AP 共用 5 GHz 信道？请提出信道规划方案。”会加载 unifi-channel-planning。

如果 Agent 没有选中某项技能，请直接指定（“使用 unifi-security 技能”）。同时搭配匹配的 UNIFI_PROFILE，也能精简工具列表。docs/SKILLS.md 提供了完整指南。

工具配置和安全控制

配置。 UNIFI_PROFILE 只注册一组模块，因此客户端会看到更少的工具定义：

配置	工具数	涵盖范围
network	48	客户端、网络、WiFi、DHCP、DNS、WAN、优惠券、信道规划
devices	53	设备、控制、迁移、端口、交换、拓扑、诊断
security	47	防火墙、ZBF、ACL、端口转发、VPN、内容过滤
system	182	站点、备份、事件、DPI、QoS、RADIUS、流量、Protect、云
protect	75	Protect 模块
mobility / innerspace / carrier	12 / 10 / 15	各自对应一个云 API
minimal	19	站点、客户端、设备

每种配置的数量都包含其必备的四个机群工具。未知配置会记录警告并加载所有工具。

安全控制。

• 所有会修改数据的工具都要求 confirm=True；dry_run=True 会返回将要进行的更改，但不会实际执行。
• UNIFI_READ_ONLY=true 会将所有修改类工具从工具列表中完全移除。UNIFI_DRY_RUN=true 会强制所有修改类调用进入预览模式。
• DEBUG=true 会添加 debug_api_request，可向任意控制器端点发送原始 GET 或 DELETE 请求。它属于破坏性级别的工具；DELETE 需要 confirm=True，只读模式会将其移除。在生产环境中不要设置 DEBUG。
• 使用令牌时，每个工具都有风险级别（read、write、destructive），每个角色也有一组风险级别：viewer 可读取，operator 可写入，admin 还可以运行破坏性工具，包括删除、恢复、重启、阻止客户端和更改防火墙策略。请参阅 API.md。
• 修改操作会写入带哈希链的 JSON 行审计日志（机群模式下使用 Postgres），并支持可选的字段加密和 SIEM 导出。请参阅 SECURITY.md。
• 输入使用 Pydantic 进行验证，凭据会从日志中脱敏。

网络传输与部署

stdio 是默认传输方式，无需端口。要通过网络提供 MCP 服务，请使用 Streamable HTTP：

export MCP_SERVER_TRANSPORT=streamable_http
export MCP_SERVER_PORT=3000
export MCP_AUTH_TOKEN=$(openssl rand -hex 32)   # required on every network transport
unifi-mcp-server
# Listening on 127.0.0.1:3000; clients send Authorization: Bearer $MCP_AUTH_TOKEN

客户端和 MCP 网关随后连接到 http://<host>:3000/mcp。除非设置 MCP_SERVER_HOST，否则服务会绑定到 127.0.0.1；在进一步对外开放之前，请在前面部署经过身份验证的 TLS 代理。http 也可用。sse 已弃用：客户端代理（例如 mcp-remote）可能会与其初始化握手发生竞争（#96）。

容器，将发布的端口绑定到回环地址：

services:
  unifi-mcp:
    image: ghcr.io/enuno/unifi-mcp-server:latest
    environment:
      UNIFI_API_KEY: your-api-key
      UNIFI_API_TYPE: local
      UNIFI_LOCAL_HOST: 192.168.2.1
      MCP_SERVER_TRANSPORT: streamable_http
      MCP_SERVER_PORT: 3000
      MCP_SERVER_HOST: 0.0.0.0          # inside the container only
      MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN}
    ports:
      - "127.0.0.1:3000:3000"

仓库中的 docker-compose.yml 会添加 Redis 和 MCP Toolbox 仪表板（MCP_TOOLBOX.md）；将 .env.docker.example 复制为 .env，然后运行 make compose-up。该示例以只读模式启动（UNIFI_READ_ONLY=true），并使用 viewer stdio 调用方（UNIFI_STDIO_ROLE=viewer）；要允许更改，请设置 UNIFI_READ_ONLY=false，并将 UNIFI_STDIO_ROLE 提升为 operator；若要进行破坏性更改，则设为 admin。

• Ansible： deploy/ansible/ 可部署独立服务、单主机集群（服务、工作进程、Redis、Postgres），或部署在多台主机上、由 nginx 代理的多个副本。若要让 AI Agent 执行部署，请从 docs/deploy-prompts/ 中的提示词开始。
• Kubernetes： deploy/helm/unifi-mcp/ 是一个 Helm chart，可用于独立服务，也可用于包含工作进程的集群模式；所有凭据均从现有 Secret 中获取。

在代码中调用服务

任何 MCP 客户端库都适用。使用 FastMCP 客户端：

import asyncio

from fastmcp import Client

config = {
    "mcpServers": {
        "unifi": {
            "command": "unifi-mcp-server",
            "env": {
                "UNIFI_API_KEY": "<your-api-key>",
                "UNIFI_API_TYPE": "local",
                "UNIFI_LOCAL_HOST": "192.168.2.1",
            },
        }
    }
}


async def main() -> None:
    async with Client(config) as client:
        sites = await client.call_tool("list_sites", {})
        print(sites.data)

        clients = await client.call_tool("list_active_clients", {"site_id": "default"})
        print(clients.data)

        # Mutations need confirm=True; dry_run=True previews the change.
        preview = await client.call_tool(
            "create_firewall_zone",
            {"site_id": "default", "name": "IoT", "confirm": True, "dry_run": True},
        )
        print(preview.data)


asyncio.run(main())

bin/unifi-cli 可从 shell 运行单个工具（unifi-cli list-clients --site default）；请参阅 docs/SKILLS.md。

原生 MCP 提示词

除工具外，该服务还通过标准 MCP 提示词接口公开八个可参数化的 UniFi 运维工作流。客户端通过 prompts/list 发现这些提示词，并通过 prompts/get 获取渲染后的工作流简介。

import asyncio

from fastmcp import Client

config = {
    "mcpServers": {
        "unifi": {
            "command": "unifi-mcp-server",
            "env": {
                "UNIFI_API_KEY": "<your-api-key>",
                "UNIFI_API_TYPE": "local",
                "UNIFI_LOCAL_HOST": "192.168.2.1",
            },
        }
    }
}


async def main() -> None:
    async with Client(config) as client:
        for prompt in await client.list_prompts():
            print(prompt.name, prompt.description)

        result = await client.get_prompt(
            "network_health_check",
            {"site_id": "default", "focus": "wan"},
        )
        for message in result.messages:
            print(message.content.text)


asyncio.run(main())

这些提示词分别为 network_health_check、troubleshoot_client_connectivity、troubleshoot_wifi_performance、investigate_device、review_firewall_policy、plan_network_change、protect_health_check 和 fleet_health_summary。只有当此服务注册了工作流所需的工具时，才会公布该工作流，因此提示词列表会随 API 模式、配置文件以及只读和试运行设置而变化。

获取提示词不会运行工作流，也不会授予任何审批权限。渲染后的文本会告知 Agent 应调用哪些读取工具以及应报告哪些内容；Agent 自行调用这些工具，而服务的角色检查、confirm 门控和审计跟踪仍然有效。

使用 make inspect 打开 MCP Inspector 并浏览提示词，或者使用 MCPJungle CLI 检查网关转发的内容：

mcpjungle list prompts --server unifi
mcpjungle get prompt unifi__network_health_check --arg site_id=default

仅支持工具的客户端不会显示提示词；这是客户端的限制。不存在将提示词转换为工具的垫片。

完整目录、可用性矩阵、验证规则和手动验收步骤，请参阅 docs/PROMPTS.md。

文档

文档	内容
API.md	所有 MCP 工具和资源，以及参数和示例
docs/PROMPTS.md	原生 MCP 提示词目录，以及参数和可用性规则
A2A.md	Agent 卡片、能力清单和委派端点
docs/AUDIT_A2A_SKILLS.md	A2A 和技能审计：已实现的内容、未实现的内容及原因
docs/SKILLS.md	Agent 技能、配置文件和 CLI 封装程序
docs/UNIFI_API.md	工具背后的 UniFi 端点
MULTI_CONTROLLER.md	Fleet 模式：控制器、令牌和角色
METRICS.md, WEBHOOK_SETUP.md, A2A.md	指标、Webhook、A2A Agent 端点
NETWORK_PLAYBOOK.md, HARBOR_SETUP.md	运维手册
SECURITY.md	漏洞报告、审计日志和加固
SPEC.md, DEVELOPMENT_PLAN.md, ROADMAP.md	架构目标和路线图
CHANGELOG.md, docs/RELEASE_PROCESS.md	发布历史，以及如何构建和发布版本

开发

git clone https://github.com/enuno/unifi-mcp-server.git
cd unifi-mcp-server
make install    # uv sync from uv.lock with the dev extra (no activation needed)
make hooks      # pre-commit and commit-msg hooks
cp .env.example .env   # then set UNIFI_API_KEY and, for local mode, UNIFI_LOCAL_HOST

make test       # unit tests
make ci         # every blocking CI check: lint, typecheck, security, docs coverage, tests with the 80% gate
make inspect    # open the server in the MCP Inspector (needs Node.js)
make help       # list every target

如果没有 make，也可以通过 uv run --locked 执行相同的命令，例如 uv run --locked pytest tests/unit/ -m "not integration"。集成测试（-m integration）需要真实的 UniFi 硬件。

目录结构：src/main.py 用于构建服务，src/tools/ 存放工具模块，src/api/ 存放 UniFi 客户端，src/models/ 存放 Pydantic 模型，src/fleet/ 存放 Fleet 技术栈，tests/unit/ 存放单元测试。AGENTS.md 和 CLAUDE.md 详细介绍了相关规范，commands.md 列出了开发命令。

贡献

欢迎个人和 AI 编码 Agent 贡献。请参阅 CONTRIBUTING.md 和 AGENTS.md。

1. Fork 此代码库并创建一个分支。
2. 先编写测试，新代码的覆盖率应达到 80% 或更高，然后运行 make ci。
3. 使用约定式提交消息（feat: ...、fix: ...），并创建拉取请求。

标题中带有 [Bug] 且由维护者或协作者创建的问题会自动进行首次分析；其他报告将由人工分类处理（详情）。

安全

请按照 SECURITY.md 中的说明报告漏洞。切勿提交凭据。

致谢

• sirkirby/unifi-network-mcp，参考实现
• MakeWithData 的 UniFi MCP 指南
• Model Context Protocol 和 FastMCP

许可证

Apache License 2.0。请参阅 LICENSE。

链接

• 问题和讨论：GitHub Issues、GitHub Discussions
• 发布版本：https://github.com/enuno/unifi-mcp-server/releases
• PyPI：https://pypi.org/project/unifi-mcp-server/
• 容器镜像：https://ghcr.io/enuno/unifi-mcp-server
• MCP Registry：在 https://registry.modelcontextprotocol.io 搜索 io.github.enuno/unifi-mcp-server