unifi-mcp

Servidor MCP remoto de solo lectura que expone la flota UniFi de Example Corp / examplecorp como conector personalizado de Claude, a través de la API oficial de UniFi Site Manager (api.ui.com).

Hermano de odoo-ticket-mcp y de los servidores MCP de TRMM — misma arquitectura:

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

• Autenticación cliente → servidor: Microsoft Entra ID, modo servidor de recursos. El servidor valida tokens de portador vinculados a la audiencia; nunca los emite. El acceso se controla mediante la pertenencia a grupos de Entra en el registro de la aplicación.

• Autenticación servidor → UniFi: una clave de API fija de Site Manager (creada en unifi.ui.com → API Keys con alcances de aplicación Site Manager + Network, Todos los sitios). La identidad del llamador NO se reenvía deliberadamente a UniFi en v1.

• Ruta de red: DNS público → nginx (TLS + lista de permitidos de IP de Anthropic) → contenedor. Defensa en profundidad: la lista de permitidos se suma a OAuth.

Herramientas (todas de solo lectura)

Site Manager (toda la flota):

Proxy de conector (profundización por consola, sin necesidad de VPN):

Flujo típico: unifi_list_hosts → elegir consola → unifi_network_sites → unifi_network_clients / unifi_network_device.

Related MCP server: UniFi MCP Server

Desarrollo local

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 abre el endpoint — solo para pruebas locales, nunca en producción.

Registro de la aplicación en Entra ID (una sola vez)

Sigue TrmmMCPServer/ENTRA_SSO_PLAYBOOK.md para la versión anotada. Resumen — haz estos pasos en orden:

1. Registros de aplicaciones → Nuevo registro — nombre UniFi MCP, un solo inquilino, sin URI de redirección todavía. Copia el id de cliente + id de inquilino.

2. Exponer una API → URI de ID de aplicación — configúralo exactamente como https://unifi-mcp.example.com/mcp (previene AADSTS9010010).

3. Exponer una API → Agregar un ámbito — access_as_user, administradores y usuarios pueden consentir, habilitado.

4. Certificados y secretos → Nuevo secreto de cliente — claude-connector, 24 meses. Copia el valor inmediatamente.

5. Autenticación → Agregar plataforma → Web — URIs de redirección https://claude.ai/api/mcp/auth_callback y https://claude.com/api/mcp/auth_callback.

6. Manifiesto — establece requestedAccessTokenVersion en 2 (previene errores 401 por discrepancia de emisor).

7. Aplicaciones empresariales → UniFi MCP → Propiedades — Asignación requerida = Sí.

8. Aplicaciones empresariales → Usuarios y grupos — agrega el grupo Unifi-MCP-Users. La pertenencia al grupo = quién puede usar el conector.

Implementación

Consulta PORTAINER_DEPLOY.md (stack de Git de Portainer + redespliegue por webhook) y deploy/nginx-unifi-mcp.conf (TLS + lista de permitidos de IP de Anthropic).

Registrar el conector en claude.ai

Configuración → Conectores → Agregar conector personalizado:

Pruebas de aceptación

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