unifi-mcp

Schreibgeschützter Remote-MCP-Server, der die UniFi-Flotte von Example Corp / examplecorp über die offizielle UniFi Site Manager API (api.ui.com) als benutzerdefinierten Connector für Claude bereitstellt.

Geschwisterprojekt von odoo-ticket-mcp und den TRMM-MCP-Servern — gleiche Architektur:

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-Authentifizierung: Microsoft Entra ID, Ressourcenserver-Modus. Der Server validiert die an die Zielgruppe (Audience) gebundenen Bearer-Tokens; er stellt sie niemals selbst aus. Der Zugriff wird über die Entra-Gruppenmitgliedschaft an der App-Registrierung gesteuert.

• Server → UniFi-Authentifizierung: ein fester Site-Manager-API-Key (erstellt unter unifi.ui.com → API Keys mit Site-Manager- und Network-Anwendungs-Scopes, „Alle Sites“). Die Identität des Aufrufers wird in v1 bewusst NICHT an UniFi weitergeleitet.

• Netzwerkpfad: öffentliches DNS → nginx (TLS + Anthropic-IP-Allowlist) → Container. Defense in Depth: Die Allowlist ist eine zusätzliche Sicherheitsmaßnahme neben OAuth.

Tools (alle schreibgeschützt)

Site-Manager (flottenweit):

Connector-Proxy (Detailabfrage pro Konsole, kein VPN erforderlich):

Typischer Ablauf: unifi_list_hosts → Konsole auswählen → unifi_network_sites → unifi_network_clients / unifi_network_device.

Related MCP server: UniFi MCP Server

Lokale Entwicklung

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 gibt den Endpunkt frei — nur für lokale Tests, niemals in der Produktion.

Entra-ID-App-Registrierung (einmalig)

In TrmmMCPServer/ENTRA_SSO_PLAYBOOK.md findest du die kommentierte Version. Zusammenfassung — führen Sie diese Schritte in der vorgegebenen Reihenfolge aus:

1. App-Registrierungen → Neue Registrierung — Name UniFi MCP, Einzelmandant, noch ohne Redirect-URI. Kopieren Sie die Client-ID und die Tenant-ID.

2. API verfügbar machen → Anwendungs-ID-URI — setzen Sie exakt auf https://unifi-mcp.example.com/mcp (verhindert AADSTS9010010).

3. API verfügbar machen → Bereich hinzufügen — `access_as_user–Administratoren und Benutzer können zustimmen, aktiviert.

4. Zertifikate und Geheimnisse → Neues Client-Secret — claude-connector, 24 Monate. Kopieren Sie den Wert sofort.

5. Authentifizierung → Plattform hinzufügen → Web — Redirect-URIs https://claude.ai/api/mcp/auth_callback und https://claude.com/api/mcp/auth_callback.

6. Manifest — setzen Sie requestedAccessTokenVersion auf 2 (verhindert 401-Fehler durch Aussteller-Mismatch).

7. Enterprise-Anwendungen → UniFi MCP → Eigenschaften — Zuweisung erforderlich = Ja.

8. Enterprise-Anwendungen → Benutzer und Gruppen — fügen Sie die Gruppe Unifi-MCP-Users hinzu. Gruppenmitgliedschaft = wer den Connector verwenden darf.

Bereitstellung

Siehe PORTAINER_DEPLOY.md (Portainer-Git-Stack + Webhook-Redeploy) und deploy/nginx-unifi-mcp.conf (TLS + Anthropic-IP-Allowlist).

Connector in claude.ai registrieren

Einstellungen → Connectors → neuen Connector hinzufügen:

Abnahmetests

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