gilberth/unifi-mcp-server-ts

UniFi MCP Server

Un servidor MCP (Model Context Protocol) para gestionar redes UniFi a través de Claude Desktop y otros clientes MCP.

Características

• 🌐 Gestión de Dispositivos: Lista y monitorea dispositivos UniFi (Access Points, Switches, Gateways)
• 👥 Gestión de Clientes: Visualiza clientes conectados y su información de red
• 📊 Monitoreo de Salud: Obtiene el estado de salud de la red y dispositivos
• 🔥 Gestión de Firewall: Lista, crea y gestiona reglas de firewall
• 📡 Configuraciones de Red: Gestiona configuraciones WLAN y de red
• 🔍 Análisis de Rendimiento: Analiza el rendimiento de la red y proporciona recomendaciones

Requisitos

• Node.js 18 o superior
• Controlador UniFi (Cloud Key, Dream Machine, o instalación local)
• Credenciales de administrador para el controlador UniFi

Instalación

Desde npm

npm install -g unifi-mcp-server

Desde el código fuente

git clone https://github.com/gilberth/unifi-mcp-server-ts.git
cd unifi-mcp-server-ts
npm install
npm run build

Configuración

Variables de Entorno

Crea un archivo .env basado en .env.example:

cp .env.example .env

Configura las siguientes variables:

UNIFI_HOST=192.168.1.1
UNIFI_USERNAME=admin
UNIFI_PASSWORD=tu_password
UNIFI_PORT=443
UNIFI_VERIFY_SSL=false
UNIFI_SITE=default

Configuración para Claude Desktop

Agrega la siguiente configuración a tu archivo claude_desktop_config.json:

{
  "mcpServers": {
    "unifi-mcp-server": {
      "command": "unifi-mcp-server",
      "env": {
        "UNIFI_HOST": "192.168.1.1",
        "UNIFI_USERNAME": "admin",
        "UNIFI_PASSWORD": "tu_password",
        "UNIFI_PORT": "443",
        "UNIFI_VERIFY_SSL": "false",
        "UNIFI_SITE": "default"
      }
    }
  }
}

Uso

Ejecución Directa

# Con npm global
unifi-mcp-server

# Con npx
npx unifi-mcp-server

# Desde el código fuente
npm start

Desarrollo

npm run dev

Herramientas Disponibles

Gestión de Dispositivos

• list_devices - Lista todos los dispositivos UniFi
• get_device_health_summary - Resumen de salud de dispositivos

Gestión de Clientes

• list_clients - Lista clientes conectados

Monitoreo de Salud

• get_system_info - Información del sistema del controlador
• get_health_status - Estado de salud del sitio
• get_isp_metrics - Métricas básicas de conectividad

Análisis de Red

• analyze_network_performance - Análisis completo del rendimiento
• query_isp_metrics - Consulta métricas específicas

Gestión de Firewall

• list_firewall_rules - Lista reglas de firewall
• get_firewall_rule - Obtiene regla específica
• create_firewall_rule - Crea nueva regla
• list_firewall_groups - Lista grupos de firewall

Configuraciones de Red

• list_wlan_configs - Lista configuraciones WLAN
• list_network_configs - Lista configuraciones de red

Seguridad

• ✅ Autenticación segura con el controlador UniFi
• ✅ Soporte para SSL/TLS
• ✅ Rate limiting para prevenir sobrecarga
• ✅ Manejo seguro de credenciales a través de variables de entorno

Desarrollo

Configuración del Entorno

git clone https://github.com/gilberth/unifi-mcp-server-ts.git
cd unifi-mcp-server-ts
npm install

Scripts Disponibles

• npm run build - Compila TypeScript a JavaScript
• npm run dev - Ejecuta en modo desarrollo con recarga automática
• npm start - Ejecuta la versión compilada
• npm run clean - Limpia archivos compilados

Ejemplos de Uso

Listar Dispositivos Online

// A través de Claude Desktop, simplemente pregunta:
// "¿Cuáles dispositivos UniFi están online?"

Analizar Rendimiento de Red

// Pregunta a Claude:
// "Analiza el rendimiento de mi red UniFi"

Crear Regla de Firewall

// Solicita a Claude:
// "Crea una regla de firewall para bloquear el puerto 22 desde cualquier IP"

Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el repositorio
2. Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
3. Commit tus cambios (git commit -am 'Agrega nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Abre un Pull Request

Licencia

MIT License - ver para más detalles.

Soporte

• 📧 Email: gilberth@gytech.com.pe
• 🐛 Issues: GitHub Issues
• 💬 Discusiones: GitHub Discussions

Changelog

v1.0.2

• Mejoras en la información del autor
• Optimizaciones en el manejo de errores
• Documentación actualizada

v1.0.1

• Correcciones menores en la autenticación
• Mejoras en el rate limiting

v1.0.0

• Lanzamiento inicial
• Soporte completo para API UniFi
• 57 herramientas disponibles
• Integración con Claude Desktop