unifi-mcp

Read-only remote MCP server exposing the Example Corp / examplecorp UniFi fleet as a Claude custom connector, via the official UniFi Site Manager API (api.ui.com).

Sibling of odoo-ticket-mcp and the TRMM MCP servers — same architecture:

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

• Client → server auth: Microsoft Entra ID, resource-server mode. The server validates audience-bound bearer tokens; it never issues them. Access is controlled by Entra group membership on the app registration.
• Server → UniFi auth: one fixed Site Manager API key (created at unifi.ui.com → API Keys with Site Manager + Network application scopes, All Sites). Caller identity is deliberately NOT forwarded to UniFi in v1.
• Network path: public DNS → nginx (TLS + Anthropic IP allowlist) → container. Defense in depth: the allowlist is in addition to OAuth.

Tools (all read-only)

Site Manager (fleet-wide):

Tool	What it returns
unifi_list_hosts	Every console (UDM Pro / UNVR / Cloud Key): id, name, model, IP, state, version
unifi_get_host	One console's detail (optional full raw record)
unifi_list_sites	All Network sites across consoles, with device/client counts
unifi_list_devices	Adopted devices fleet-wide (APs, switches, gateways), optional per-console filter
unifi_isp_metrics	WAN/ISP health (latency, loss, downtime, throughput) for all sites, 5m or 1h granularity
unifi_query_isp_metrics	Same, but for specific (host, site) pairs and windows
unifi_list_sdwan_configs / unifi_sdwan_config_status	SD-WAN topologies + deployment state

Connector proxy (per-console drill-down, no VPN needed):

Tool	What it returns
unifi_network_sites	Console-local site list (local ids differ from Site Manager ids)
unifi_network_devices	A site's devices from the console's own Network API
unifi_network_device	Full device detail + latest live stats (CPU, memory, uplink, radios)
unifi_network_clients	Live connected clients: name, MAC, IP, connection type, uplink

Typical flow: unifi_list_hosts → pick console → unifi_network_sites → unifi_network_clients / unifi_network_device.

Local development

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 opens the endpoint — local testing only, never in production.

Entra ID app registration (one-time)

Follow TrmmMCPServer/ENTRA_SSO_PLAYBOOK.md for the annotated version. Summary — do these in order:

1. App registrations → New registration — name UniFi MCP, single tenant, no redirect URI yet. Copy the client id + tenant id.
2. Expose an API → Application ID URI — set to exactly https://unifi-mcp.example.com/mcp (prevents AADSTS9010010).
3. Expose an API → Add a scope — access_as_user, admins and users can consent, enabled.
4. Certificates & secrets → New client secret — claude-connector, 24 months. Copy the value immediately.
5. Authentication → Add platform → Web — redirect URIs https://claude.ai/api/mcp/auth_callback and https://claude.com/api/mcp/auth_callback.
6. Manifest — set requestedAccessTokenVersion to 2 (prevents issuer-mismatch 401s).
7. Enterprise applications → UniFi MCP → Properties — Assignment required = Yes.
8. Enterprise applications → Users and groups — add the Unifi-MCP-Users group. Group membership = who can use the connector.

Deploy

See PORTAINER_DEPLOY.md (Portainer Git stack + webhook redeploy) and deploy/nginx-unifi-mcp.conf (TLS + Anthropic IP allowlist).

Register the connector in claude.ai

Settings → Connectors → Add custom connector:

Field	Value
URL	https://unifi-mcp.example.com/mcp
Client ID	the Entra app's client id
Client Secret	the Entra client secret
Authorization URL	https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize
Token URL	https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
Scopes	https://unifi-mcp.example.com/mcp/access_as_user

Acceptance tests

# 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.