UniFi MCP Server

mcp-name: io.github.mikeholownych/unifi-mcp

Un servidor MCP (Model Context Protocol) que proporciona a asistentes de IA como Claude acceso a las capacidades de gestión y análisis de la infraestructura de UniFi Network y Protect.

Créditos: Este proyecto comenzó como un fork de gbassaragh/Unifi-mcp y desde entonces ha evolucionado hasta convertirse en un proyecto totalmente independiente. Gracias a @gbassaragh por el excelente punto de partida.

Mejoras respecto al upstream

• Corregido el enrutamiento de autenticación de sesión local — en UNIFI_MODE=local, las peticiones ahora usan correctamente la API del controlador tradicional (/proxy/network) con autenticación de sesión por cookie + CSRF. El upstream siempre enrutaba a través de la Integration API independientemente del modo.

• Resolución de URL base según el modo — api_base_url ahora respeta el modo de autenticación configurado en lugar de devolver incondicionalmente el endpoint de la Integration API.

• Suite de pruebas ampliada — 57 pruebas superadas que cubren configuración, comportamiento del cliente de red, registro de herramientas del servidor e integraciones con Protect.

Related MCP server: UniFi MCP Server

Características

UniFi Network

• Gestión de dispositivos: Listar, reiniciar, localizar y actualizar dispositivos UniFi (APs, switches, routers)

• Gestión de clientes: Supervisar clientes conectados, bloquear/desbloquear, ver estadísticas de tráfico

• Gestión de sitios: Ver la salud del sitio, configuraciones de red, VLANs y ajustes inalámbricos

• Estadísticas y supervisión: Eventos, alarmas, pruebas de velocidad y estadísticas DPI

• Información basada en IA: Análisis de red, recomendaciones de optimización y resolución de problemas

UniFi Protect

• Gestión de cámaras: Listar cámaras, ver el estado, obtener instantáneas en vivo

• Supervisión del sistema: Estado del NVR, resúmenes de salud de las cámaras

• Accesorios: Gestionar luces, sensores, timbres y visores

• Liveviews: Acceder a las distribuciones de vistas de cámara configuradas

Compatibilidad con múltiples dispositivos

• Configurar varios dispositivos UniFi (gateways, NVRs, etc.)

• Dirigirse a dispositivos específicos por nombre: todas las herramientas de red y Protect aceptan un parámetro opcional device

• Claves de API por dispositivo: cada dispositivo configurado se autentica con su propia clave

• Combinación de servicios de Network y Protect entre dispositivos

Modos de autenticación

Cuando se utilizan claves de API (Integration API), un subconjunto de las funciones del controlador solo está disponible mediante la autenticación de sesión heredada (UNIFI_MODE=local): eventos de red, alarmas, estadísticas DPI, pruebas de velocidad, configuraciones WLAN, reglas de firewall, perfiles de puerto y tablas de enrutamiento. Las herramientas para estas funciones devuelven un error claro que explica cómo habilitarlas en lugar de fallar silenciosamente. Las herramientas de información se degradan con elegancia y notifican las limitaciones de los datos.

Nota sobre cuentas locales: Los administradores con SSO/cuenta de Ubiquiti protegidos por MFA no pueden completar el inicio de sesión. Crea un administrador local en tu consola (Restrict to Local Access Only) para UNIFI_MODE=local.

Habilidades del agente

Las habilidades incluidas (en skills/) enseñan a los agentes flujos de trabajo probados para este servidor, incluidas las particularidades específicas del controlador (endpoints eliminados en Network 10, reglas de pares de zonas, transición WPA3).

Documentación completa: Consulta SKILLS.md para la guía de uso, los resultados esperados, la resolución de problemas y cómo solicitar nuevas funcionalidades.

Referencia rápida

Cómo funcionan las habilidades

Simplemente describe tu problema con naturalidad: el agente asocia tu solicitud con la habilidad adecuada y sigue su flujo de trabajo:

• «Mi internet está caído» → unifi-internet-down diagnostica WAN, módem, gateway

• «¿Quién está en mi WiFi?» → unifi-whos-home lista los dispositivos y marca los desconocidos

• «Audita mi red» → unifi-network-audit genera un informe de salud completo

• «Configura mi nueva TV» → unifi-setup-new-device guía el emparejado WiFi

Las habilidades con bloqueo de escritura (marcadas arriba) modifican tu red: siempre piden aprobación antes de aplicar cambios.

Las habilidades para usuarios no técnicos evitan la jerga, traducen cada término técnico y requieren confirmación antes de realizar acciones disruptivas.

Instalación (por proyecto): copia en .claude/skills/:

git clone https://github.com/mikeholownych/unifi-mcp.git
mkdir -p .claude/skills && cp -r unifi-mcp/skills/* .claude/skills/

Consulta SKILLS.md para la guía de uso completa, los resultados esperados, la resolución de problemas y cómo solicitar nuevas funcionalidades.

Las habilidades referencian las herramientas MCP por sus nombres simples (get_firewall_policies, …); tu cliente MCP les añade el prefijo automáticamente.

Hardware compatible

• UniFi Dream Machine (UDM, UDM-Pro, UDM-SE)

• UniFi Cloud Gateway (UCG-Ultra, UCG-Fiber)

• UniFi Network Video Recorder (UNVR, UNVR-Pro)

• UniFi Network Application (autoalojada)

• Cloud Key tradicional (Gen1, Gen2, Gen2+)

Instalación

Usando uv (Recomendado)

# Clone the repository
git clone https://github.com/mikeholownych/unifi-mcp.git
cd unifi-mcp

# Install dependencies
uv sync

Usando pip

pip install -e .

Configuración

Crea un archivo .env en la raíz del proyecto (o define las variables de entorno). Consulta .env.example para ver todas las opciones.

Configuración de múltiples dispositivos (Recomendada)

Configura varios dispositivos UniFi con diferentes servicios:

UNIFI_DEVICES='[
  {
    "name": "main-gateway",
    "url": "https://192.168.1.1",
    "api_key": "your-gateway-api-key",
    "services": ["network"],
    "site": "default"
  },
  {
    "name": "nvr",
    "url": "https://192.168.1.2",
    "api_key": "your-nvr-api-key",
    "services": ["network", "protect"],
    "site": "default"
  }
]'
UNIFI_VERIFY_SSL=false

Campos de configuración del dispositivo:

Nota: Los campos username y password solo son necesarios para las herramientas de eventos de Protect (eventos de movimiento, detecciones inteligentes). Las operaciones básicas de cámara funcionan solo con la clave de API.

Para crear una clave de API:

1. Inicia sesión en tu controlador UniFi

2. Ve a Ajustes → Control Plane → API

3. Crea una nueva clave de API con los permisos adecuados

Configuración heredada de un solo dispositivo

Por compatibilidad con versiones anteriores, la configuración de un solo dispositivo sigue siendo compatible:

UNIFI_MODE=local_api_key
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_CLOUD_API_KEY=your-api-key
UNIFI_SITE=default
UNIFI_VERIFY_SSL=false

Autenticación de sesión local (tradicional)

Para acceso completo a funciones con autenticación de usuario/contraseña:

UNIFI_MODE=local
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_USERNAME=local-admin
UNIFI_PASSWORD=your-password
UNIFI_SITE=default
UNIFI_IS_UDM=true
UNIFI_VERIFY_SSL=false

API en la nube (api.ui.com)

Para acceso a la API en la nube de Ubiquiti:

UNIFI_MODE=cloud
UNIFI_CLOUD_API_KEY=your-api-key

Obtén tu clave de API desde unifi.ui.com → sección API.

Uso con Claude Desktop

Añade a tu configuración de Claude Desktop (~/.config/claude/claude_desktop_config.json en Linux o ~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "unifi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/unifi-mcp", "python", "-m", "unifi_mcp.server"],
      "env": {
        "UNIFI_DEVICES": "[{\"name\":\"gateway\",\"url\":\"https://192.168.1.1\",\"api_key\":\"your-key\",\"services\":[\"network\"]},{\"name\":\"nvr\",\"url\":\"https://192.168.1.2\",\"api_key\":\"your-key\",\"services\":[\"network\",\"protect\"]}]",
        "UNIFI_VERIFY_SSL": "false"
      }
    }
  }
}

Uso con Claude Code / opencode

# Add the MCP server
claude mcp add unifi -- uv run --directory /path/to/unifi-mcp python -m unifi_mcp.server

O en opencode.json:

{
  "mcp": {
    "unifi": {
      "type": "local",
      "command": ["/path/to/unifi-mcp/.venv/bin/python", "-m", "unifi_mcp.server"],
      "enabled": true
    }
  }
}

Herramientas disponibles

Gestión de múltiples dispositivos

• list_unifi_devices - Lista todos los dispositivos UniFi configurados y sus servicios

Gestión de dispositivos

• list_devices - Lista todos los dispositivos de red UniFi

• get_device_details - Obtiene información detallada del dispositivo

• restart_device - Reinicia un dispositivo

• locate_device - Parpadear el LED para localizar el dispositivo

• get_device_stats - Obtiene estadísticas de rendimiento

• upgrade_device - Actualiza el firmware

• provision_device - Fuerza el reaprovisionamiento

Gestión de clientes

• list_clients - Lista los clientes conectados

• list_all_clients - Lista todos los clientes conocidos (incluidos los desconectados)

• get_client_details - Obtiene los detalles del cliente

• block_client / unblock_client - Bloquear/desbloquear clientes

• kick_client - Desconecta un cliente

• forget_client - Elimina de los clientes conocidos

• get_client_traffic - Obtiene las estadísticas de tráfico

• reserve_client_ip - Reservar IP mediante reserva DHCP

Gestión de sitios

• list_sites - Lista todos los sitios

• get_site_health - Obtiene el estado de salud del sitio

• get_site_settings - Obtiene los ajustes del sitio

• get_sysinfo - Obtiene la información del sistema

• get_networks - Obtiene las configuraciones de red/VLAN

• get_wlans - Obtiene las configuraciones de red inalámbrica

• get_port_profiles - Obtiene los perfiles de puerto del switch

• get_firewall_rules - Obtiene las reglas de firewall heredadas

• get_firewall_policies - Obtiene las políticas de firewall basadas en zonas (UniFi Network 9+)

• get_routing_table - Obtiene la tabla de enrutamiento

• get_port_forwards - Obtiene las reglas de reenvío de puertos

• create_port_forward / delete_port_forward - Gestiona los reenvíos de puertos

Gestión de configuración (escrituras)

• create_wlan / update_wlan / delete_wlan - Gestionar redes inalámbricas

• create_firewall_policy / set_firewall_policy_enabled / delete_firewall_policy - Gestionar políticas de firewall basadas en zonas

• export_camera_clip - Exportar un clip de grabación de cámara como MP4 (Protect)

• get_all_sites_health - Resumen de salud en todos los sitios

Las herramientas que eliminan datos o causan interrupciones están sujetas a confirmación o se marcan como destructivas mediante anotaciones de MCP.

Estadísticas y monitorización

• get_network_health - Salud general de la red

• get_recent_events - Eventos recientes

• get_alarms - Alarmas activas

• archive_all_alarms - Archivar todas las alarmas

• run_speed_test - Iniciar prueba de velocidad

• get_speed_test_status - Obtener resultados de la prueba de velocidad

• get_dpi_stats - Estadísticas de DPI

• get_traffic_summary - Resumen de tráfico

Herramientas de información de IA

• analyze_network_issues - Análisis exhaustivo de problemas

• get_optimization_recommendations - Recomendaciones de configuración

• get_client_experience_report - Métricas de calidad del cliente

• get_device_health_summary - Resumen de salud de dispositivos

• get_traffic_analysis - Análisis de patrones de tráfico

• get_all_sites_health - Resumen de salud en todos los sitios

Orquestación multi-sitio

• get_global_inventory - Inventario unificado de dispositivos en todos los controladores

• get_global_health - Informe de salud agregado de todos los controladores

• get_global_client_summary - Conteos de clientes, principales consumidores de tráfico y clientes bloqueados en todos los controladores

• troubleshoot_client - Diagnóstico detallado de clientes

UniFi Protect

• list_cameras - Listar todas las cámaras con su estado de conexión

• get_camera_details - Obtener información detallada de la cámara

• get_camera_snapshot - Obtener instantánea en vivo (JPEG en base64)

• get_protect_system_info - Obtener información del sistema NVR

• get_camera_health_summary - Resumen de salud de cámaras con incidencias

• get_liveviews - Obtener los diseños de vista en vivo configurados

• get_protect_accessories - Listar luces, sensores, timbres y visores

Eventos de UniFi Protect (requieren nombre de usuario/contraseña)

• get_motion_events - Obtener eventos de movimiento recientes

• get_smart_detections - Obtener eventos de detección inteligente (persona, vehículo, animal, paquete)

• get_protect_event_summary - Resumen de todos los eventos por tipo

• get_recent_protect_activity - Descripción general rápida de la actividad reciente

Conversaciones de ejemplo

Después de conectar el servidor MCP, puedes preguntar a Claude:

Gestión de red

• "Lista todos mis dispositivos UniFi"

• "¿Cuál es la salud actual de la red?"

• "Analiza mi red para detectar problemas"

• "¿Qué recomendaciones de optimización tienes?"

• "Muéstrame las métricas de experiencia del cliente"

• "Diagnostica al cliente con MAC aa:bb:cc:dd:ee:ff"

• "¿Qué clientes están usando más ancho de banda?"

• "¿Hay algún dispositivo que necesite actualizaciones de firmware?"

• "Muéstrame los eventos de red recientes"

• "Ejecuta una prueba de velocidad"

UniFi Protect

• "Lista todas mis cámaras"

• "Muéstrame el resumen de salud de las cámaras"

• "Obtén una instantánea de la cámara de la puerta principal"

• "¿Cuál es el estado de mi NVR?"

• "¿Hay alguna cámara desconectada?"

• "Muéstrame los accesorios de Protect"

Eventos de Protect (requiere credenciales)

• "Muéstrame los eventos de movimiento recientes"

• "¿Qué detecciones inteligentes ocurrieron en las últimas 24 horas?"

• "¿Hubo detecciones de personas hoy?"

• "Dame un resumen de eventos de la última semana"

• "Muestra la actividad reciente de la cámara de la puerta principal"

Multi-dispositivo

• "Lista mis dispositivos UniFi configurados"

• "Muestra las cámaras de mi NVR"

• "Obtén la salud de la red desde la puerta de enlace principal"

Desarrollo

Ejecutar pruebas

uv run pytest

Formato de código

uv run ruff check .
uv run ruff format .

Docker

docker build -t unifi-mcp .
docker run -i --rm --env-file .env unifi-mcp

Solicitar nuevas funcionalidades

• Nuevas habilidades: Abre un issue con el prefijo [Skill] — describe el problema, el flujo de trabajo y el resultado esperado

• Modificar habilidades: Abre un issue con el prefijo [Skill: skill-name] — qué falta o qué no funciona

• Nuevas herramientas: Abre un issue con el prefijo [Tool] — incluye el endpoint de la API de UniFi y el formato esperado

Consulta SKILLS.md para obtener directrices detalladas de contribución.

Consulta CHANGELOG.md para ver el historial de versiones y CONTRIBUTING.md para contribuir.

Notas de seguridad

• Las credenciales se pasan mediante variables de entorno — nunca hagas commit de .env

• La verificación SSL está deshabilitada de forma predeterminada para certificados autofirmados

• El servidor solo expone operaciones de lectura y comandos de gestión seguros

• Las operaciones destructivas (eliminar sitio, restablecimiento de fábrica) no están expuestas

• Las claves de API deben mantenerse seguras y rotarse periódicamente

Licencia

MIT License

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, abre un issue o envía una pull request.