UniFi Access MCP

UniFi Access MCP 服务

此 MCP 服务向 AI 助手及其他支持 MCP 的客户端提供 UniFi Access 工具。管理门禁、凭证、访问策略、访客、事件和设备，并采用默认安全的权限设置，所有变更都必须先预览再确认。

通过 HTTP 集成的软件，包括自动化服务和 MCP 适配器，应使用 unifi-api-server 执行 REST 和 GraphQL 读取、操作及 SSE 事件处理。

安装

Claude Code（推荐）

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

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

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

/unifi-access:unifi-access-setup

设置过程会引导你连接 Access 控制器，说明双重身份验证系统（读取使用 API 密钥，变更使用用户名和密码），并配置权限。凭证通过文件或命令提供程序传入，绝不会在聊天中输入。设置会将结果保存为插件的 Claude Code 选项，这些选项适用于每个项目；作为选项输入的密码或 API 密钥会存储在系统密钥链中。设置完成后，启动新的 Claude Code 会话以连接。

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

Codex

注册市场，然后从 Codex 的 /plugins 界面安装 unifi-access：

codex plugin marketplace add sirkirby/unifi-mcp

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

PyPI / Docker

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

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

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

使用示例

连接后，只需用自然语言向 AI Agent 提出请求：

“今天有谁刷卡进入办公室？给我查看所有门禁事件的时间线。”

“列出未来 30 天内到期的所有访问凭证。”

“查看本周服务器机房的刷卡失败尝试——有没有什么规律？”

“今天哪些门发生的门禁事件最多？”

“为 John Smith 创建访客通行证，允许他明天上午 9 点至下午 5 点从主入口进入。”

“审核门禁策略——哪些门允许在营业时间以外进入？”

所有查询默认均为只读操作。变更（访客通行证、凭证更改、门禁控制）采用先预览再确认的流程。

配置

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

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

# Server-specific variables (recommended)
UNIFI_ACCESS_HOST=192.168.1.1      # Controller IP or hostname
UNIFI_ACCESS_USERNAME=admin         # Local admin username
UNIFI_ACCESS_PASSWORD=your-password # Admin password
# Optional:
# UNIFI_ACCESS_API_KEY=             # Official UniFi API key (dual auth)
# UNIFI_ACCESS_PORT=443             # Controller HTTPS port
# UNIFI_ACCESS_VERIFY_SSL=false     # SSL certificate verification

**备用方式：**也可以使用共享的 UNIFI_* 变量（例如 UNIFI_HOST）。服务会优先检查 UNIFI_ACCESS_*；如果未设置特定于服务的变量，则回退到 UNIFI_*。对于单控制器设置，只需使用共享变量即可。

MCP 响应大小

对于本身已提供结构化输出的工具结果，默认响应模式为 adaptive。该模式根据 MCP 初始化期间公布的规范日期版本 protocolVersion 对每个请求进行分类，而非根据客户端的产品名称或应用版本。对于公布 MCP 2025-06-18 或更高版本的请求，响应会包含简洁的 content，并在 structuredContent 中完整返回一次结果；对于公布较早版本（如 2024-11-05 或 2025-03-26）的请求，或版本元数据缺失或格式错误的请求，则会在 content 中保留完整的兼容性 JSON。将 UNIFI_ACCESS_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。

启用 Access 的同时也启用 Network 时，其最大的源响应会分别受到限制：unifi_get_dashboard 默认使用 summary=true，unifi_list_rogue_aps 默认返回最多包含 100 条记录的摘要页面；summary=false 可恢复完整的所选数据。

双重身份验证

Access 服务支持两条独立的身份验证路径：

1. API key -- 在专用 Access API 端口（默认 12445）上使用 py-unifi-access。最适合只读查询和设备列表。
2. 本地代理会话 -- 通过 UniFi OS Console（端口 443）上的 /api/auth/login 登录，并通过 /proxy/access/api/v2/... 代理请求。门锁控制、凭据管理、策略、访客和事件操作都需要此方式。

至少必须配置一条路径。两种方式都可用时，每个工具都会选择最合适的路径。大多数有更改操作的工具都需要本地代理会话。

密钥脱敏

Access 工具默认会在向 MCP 客户端返回数据前对凭据密钥进行脱敏 — 在读取、列表和创建预览中，凭据的 token 和 pin_code 值会显示为 ***REDACTED***。如果可信的本地管理流程需要原始值，可将 UNIFI_ACCESS_REDACT_SENSITIVE_FIELDS=false 设为禁用脱敏，或使用全局策略标志 UNIFI_REDACT_SENSITIVE_FIELDS=false。更新时若要保留现有密钥，请省略该字段，而不要将 ***REDACTED*** 标记传回（该标记会被拒绝）。

运行

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

# Docker
docker run -i --rm \
  -e UNIFI_ACCESS_HOST=192.168.1.1 \
  -e UNIFI_ACCESS_USERNAME=admin \
  -e UNIFI_ACCESS_PASSWORD=secret \
  ghcr.io/sirkirby/unifi-access-mcp:latest

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "unifi-access": {
      "command": "uvx",
      "args": ["unifi-access-mcp"],
      "env": {
        "UNIFI_ACCESS_HOST": "192.168.1.1",
        "UNIFI_ACCESS_USERNAME": "admin",
        "UNIFI_ACCESS_PASSWORD": "your-password"
      }
    }
  }
}

功能

• 门 -- 列出、检查、锁定/解锁门，查看门组和实时状态
• 策略 -- 列出、检查和更新访问策略与时间表
• 凭据 -- 列出、检查、创建和撤销 NFC 卡、PIN 码及移动凭据
• 访客 -- 列出、检查、创建和删除具有时限访问权限的访客通行证
• 事件 -- 查询历史事件、查看实时 WebSocket 缓冲区和活动摘要
• 设备 -- 列出、检查和重启门禁集线器、读卡器、继电器及对讲机
• 系统 -- 控制器信息、运行状况指标、用户列表

Agent 技能

Claude Code 插件附带 Agent 技能，可教会 AI 助手如何有效使用 Access：

• UniFi Access — 用于门禁控制、凭证、访客、访问策略和事件监控的核心技能。包含双重身份验证系统、通过 WebSocket 缓冲区实时流式传输事件，以及实体门禁操作的预览确认流程的指导。
• Setup — 交互式配置向导，引导用户完成控制器连接、凭证设置和权限配置。

安装插件后，技能会自动启用。

跨产品技能

如果安装 Access 插件时也安装了 Protect 插件，security-digest 技能便可将门禁事件纳入分析。徽章刷卡、访问遭拒事件和非工作时间的门禁记录会与 Protect 的摄像头动态和警报关联起来，从而为整个 UniFi 部署生成更全面的安全摘要。

无需额外配置 — 如果两个插件都处于启用状态，该技能会自动从两个服务获取数据。

文档

• 配置 -- 完整的环境变量参考、YAML 配置和 Access 专属选项
• 权限 -- 权限系统、类别默认值以及如何启用修改操作
• 工具目录 -- 按类别整理的全部 37 个工具
• 事件流 -- 实时事件架构、WebSocket 缓冲区和轮询
• 故障排除与支持包 -- 经审核的支持证据、双重身份验证调试和缺失工具

开发

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

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

许可证

MIT