unifi-mcp
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 APIAutenticació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):
Tool | Qué devuelve |
| Cada consola (UDM Pro / UNVR / Cloud Key): id, nombre, modelo, IP, estado, versión |
| Detalle de una consola (registro completo sin procesar opcional) |
| Todos los sitios de Network en todas las consolas, con recuentos de dispositivos/clientes |
| Dispositivos adoptados en toda la flota (APs, switches, gateways), filtro opcional por consola |
| Salud de WAN/ISP (latencia, pérdida, tiempo de inactividad, rendimiento) para todos los sitios, granularidad de 5m o 1h |
| Lo mismo, pero para pares (host, sitio) y ventanas específicos |
| Topologías SD-WAN + estado de implementación |
Proxy de conector (profundización por consola, sin necesidad de VPN):
Tool | Qué devuelve |
| Lista de sitios local de la consola (los ids locales difieren de los ids de Site Manager) |
| Dispositivos de un sitio desde la propia API de Network de la consola |
| Detalle completo del dispositivo + estadísticas en vivo más recientes (CPU, memoria, uplink, radios) |
| Clientes conectados en vivo: nombre, MAC, IP, tipo de conexión, uplink |
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:
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.Exponer una API → URI de ID de aplicación — configúralo exactamente como
https://unifi-mcp.example.com/mcp(previene AADSTS9010010).Exponer una API → Agregar un ámbito —
access_as_user, administradores y usuarios pueden consentir, habilitado.Certificados y secretos → Nuevo secreto de cliente —
claude-connector, 24 meses. Copia el valor inmediatamente.Autenticación → Agregar plataforma → Web — URIs de redirección
https://claude.ai/api/mcp/auth_callbackyhttps://claude.com/api/mcp/auth_callback.Manifiesto — establece
requestedAccessTokenVersionen2(previene errores 401 por discrepancia de emisor).Aplicaciones empresariales → UniFi MCP → Propiedades — Asignación requerida = Sí.
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:
Campo | Valor |
URL |
|
ID de cliente | el id de cliente de la aplicación de Entra |
Secreto de cliente | el secreto de cliente de Entra |
URL de autorización |
|
URL de token |
|
Ámbitos |
|
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.Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Manage hosts, redirects, SSL, and traffic analytics from Claude and other AI assistants.
Read-only access to your own crypto portfolio across 11+ exchanges and 20+ chains: holdings, full history, FIFO cost basis and P&L, fees and income. Ask Claude or ChatGPT about your portfolio; the connector can never trade, move funds or act as a login.
Read-only Google Ads, GA4 and Search Console data for Claude, with no Google Cloud setup.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Related MCP Servers
- AlicenseDqualityNot gradedmaintenanceEnables comprehensive management of UniFi network infrastructure through the UniFi Cloud API, including device control, client management, camera settings, and access door control through natural language.39MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to manage and monitor UniFi Network Controllers through natural language. Provides 25 read-only tools for discovering devices and clients, viewing security configurations, analyzing network statistics, and exporting configuration data.41MIT
- FlicenseNot gradedqualityBmaintenanceRead-only MCP server that surfaces UniFi network data from a UCG-Fiber console to Claude, enabling monitoring of hosts, sites, devices, clients, ISP metrics, and device stats via read-only API tools.-
- AlicenseNot gradedqualityCmaintenanceEnables Claude to read-only observe a UniFi network through Ubiquiti's cloud API, including connected clients, device health, throughput, and ISP/WAN status, with OAuth-gated access to a single account.1MIT