unifi-mcp

只读远程 MCP 服务器，通过官方 UniFi Site Manager API（api.ui.com）将 Example Corp / examplecorp 的 UniFi 设备群暴露为 Claude 自定义连接器。

是 odoo-ticket-mcp 和 TRMM MCP servers 的同类项目，架构相同：

Claude (claude.ai / Claude Code)
   │  OAuth 2.0 bearer token (Microsoft Entra ID)
   ▼
nginx  — TLS, Anthropic egress-IP allowlist (160.79.104.0/21), 403 otherwise
   │  http://127.0.0.1:8097
   ▼
unifi-mcp container (Portainer stack, FastMCP 3.x, Streamable HTTP at /mcp)
   │  X-API-KEY (Site Manager API key, read-only usage)
   ▼
api.ui.com  — Site Manager API + connector proxy into each console's Network API

• 客户端 → 服务器认证： Microsoft Entra ID，资源服务器模式。服务器验证已绑定受众的 bearer token；它从不颁发这些 token。访问权限由应用注册上的 Entra 组成员身份控制。

• 服务器 → UniFi 认证： 一个固定的 Site Manager API 密钥（在 unifi.ui.com → API Keys 中创建，具有 Site Manager + Network 应用范围，All Sites）。调用方身份在 v1 中有意不转发给 UniFi。

• 网络路径： 公共 DNS → nginx（TLS + Anthropic IP 允许列表）→ 容器。纵深防御：允许列表是在 OAuth 之外额外增加的。

工具（全部只读）

Site Manager（全设备群）：

连接器代理（按控制台下钻，无需 VPN）：

典型流程：unifi_list_hosts → 选择控制台 → unifi_network_sites → unifi_network_clients / unifi_network_device。

Related MCP server: UniFi MCP Server

本地开发

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
copy .env.example .env    # fill in UNIFI_API_KEY; set MCP_AUTH_ENABLED=false
.venv\Scripts\python -m unifi_mcp
# → http://127.0.0.1:8000/mcp  (test with MCP Inspector)

MCP_AUTH_ENABLED=false 会开放该端点——仅用于本地测试，切勿在生产环境中使用。

Entra ID 应用注册（一次性）

带注释的版本请参阅 TrmmMCPServer/ENTRA_SSO_PLAYBOOK.md。摘要——请按顺序完成以下操作：

1. 应用注册 → 新建注册 — 名称为 UniFi MCP，单租户，暂不设置重定向 URI。复制 client id 和 tenant id。

2. 公开 API → Application ID URI — 必须准确设置为 https://unifi-mcp.example.com/mcp（防止出现 AADSTS9010010）。

3. 公开 API → 添加范围 — access_as_user，管理员和用户可以同意，已启用。

4. 证书和机密 → 新建客户端机密 — claude-connector，24 个月。立即复制该值。

5. 身份验证 → 添加平台 → Web — 重定向 URI 为 https://claude.ai/api/mcp/auth_callback 和 https://claude.com/api/mcp/auth_callback。

6. 清单 — 将 requestedAccessTokenVersion 设置为 2（防止签发者不匹配的 401 错误）。

7. 企业应用程序 → UniFi MCP → 属性 — 需要分配 = 是。

8. 企业应用程序 → 用户和组 — 添加 Unifi-MCP-Users 组。组成员身份 = 谁可以使用该连接器。

部署

请参阅 PORTAINER_DEPLOY.md（Portainer Git stack + webhook 重新部署）和 deploy/nginx-unifi-mcp.conf（TLS + Anthropic IP 允许列表）。

在 claude.ai 中注册连接器

设置 → 连接器 → 添加自定义连接器：

验收测试

# 1. Discovery doc advertises the full resource scope (not api://…)
curl -s https://unifi-mcp.example.com/.well-known/oauth-protected-resource/mcp | jq .scopes_supported

# 2. Unauthenticated /mcp is challenged
curl -i https://unifi-mcp.example.com/mcp        # 401 + WWW-Authenticate: Bearer

# 3. Non-Anthropic source IP is blocked at nginx
curl -i https://unifi-mcp.example.com/mcp        # from anywhere else: 403

# 4. Health (host-local, bypasses nginx)
curl http://<docker-host>:8097/healthz                 # {"status":"ok","service":"unifi_mcp"}

# 5. In claude.ai: connect as a Unifi-MCP-Users member → tools appear;
#    non-member → AADSTS50105 at sign-in.