Nanoleaf MCP Server

Un servidor para controlar luces inteligentes Nanoleaf mediante el Protocolo de Contexto del Modelo.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de Nanoleaf

Un servidor de Model Context Protocol (MCP) para controlar luces inteligentes Nanoleaf. Este servidor proporciona herramientas para controlar tus dispositivos Nanoleaf a través de la terminal Warp o cualquier cliente compatible con MCP.

Nanoleaf Server MCP server

Características

  • 🔍 Auto-descubrimiento de dispositivos Nanoleaf en tu red
  • 🔗 Conexión IP directa para apuntar a dispositivos específicos
  • 🔐 Soporte de autorización para emparejamiento seguro de dispositivos
  • 💡 Control completo de luces, brillo, colores y efectos
  • 🐳 Dockerizado para fácil implementación
  • 🖥️ Integración con terminal Warp
  • 🔒 Dependencias auditadas en seguridad con verificaciones regulares de vulnerabilidades

Herramientas Disponibles

  • get_nanoleaf_info - Obtener información detallada del dispositivo
  • turn_on_nanoleaf / turn_off_nanoleaf - Controlar estado de encendido/apagado
  • set_brightness - Ajustar brillo (0-100)
  • set_color - Establecer color usando tono (0-360) y saturación (0-100)
  • set_effect - Aplicar efectos de iluminación
  • get_effects - Listar todos los efectos disponibles
  • discover_nanoleaf - Descubrir dispositivos en la red
  • connect_to_ip - Conectar a una dirección IP específica
  • authorize_nanoleaf - Autorizar con dispositivo en modo de emparejamiento

Guía de Configuración Rápida

Configuración Automatizada (Recomendada)

Para la experiencia de configuración más fácil, usa el script de configuración incluido:

./setup.sh

Este script:

  1. Construirá la imagen Docker
  2. Escaneará dispositivos Nanoleaf en tu red
  3. Te ayudará a obtener el token de autorización
  4. Creará todos los archivos de configuración
  5. Probará la configuración
  6. Generará tu configuración de Warp

Configuración Manual

Requisitos Previos

  • Docker instalado en tu sistema
  • Dispositivo(s) Nanoleaf en tu red
  • Terminal Warp (opcional, para integración MCP)

Paso 1: Clonar y Construir

git clone <repository-url>
cd nanoleaf-mcp-server
docker build -t nanoleaf-mcp-server-nanoleaf-mcp-server .

Paso 2: Encontrar Tu Dispositivo Nanoleaf

Opción A: Auto-descubrimiento

docker run --rm -i --network=host nanoleaf-mcp-server echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "discover_nanoleaf", "arguments": {}}}'

Opción B: Escaneo manual de IP

# Scan your network for devices responding on Nanoleaf port
nmap -p 16021 192.168.1.0/24

Opción C: Revisar el panel de administración del router para dispositivos conectados

Paso 3: Obtener Token de Autorización

  1. Pon tu dispositivo Nanoleaf en modo de emparejamiento:

    • Mantén presionado el botón de encendido en tu dispositivo Nanoleaf durante 5-7 segundos
    • Busca el indicador de emparejamiento (generalmente una luz parpadeante)

  2. Obtén el token de autenticación inmediatamente (dentro de 30 segundos):

    # Replace 192.168.1.100 with your device's IP
curl -X POST http://192.168.1.100:16021/api/v1/new

    Deberías recibir una respuesta como:

    {"auth_token":"YourAuthTokenHere123456789"}

Paso 4: Configurar Variables de Entorno

Crea un archivo .env en el directorio del proyecto:

NANOLEAF_IP=192.168.1.100
NANOLEAF_AUTH_TOKEN=YourAuthTokenHere123456789
NANOLEAF_PORT=16021
NANOLEAF_PROTOCOL=http

Paso 5: Probar Tu Configuración

# Test with environment variables
docker run --rm -i --network=host --env-file .env nanoleaf-mcp-server echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_nanoleaf_info", "arguments": {}}}'

¡Si tiene éxito, verás información detallada sobre tu dispositivo Nanoleaf!

Paso 6: Ejecutar Ejemplos (Opcional)

Prueba toda la funcionalidad con el script de ejemplo:

./examples.sh

Esto demostrará todas las características disponibles, incluyendo encender/apagar luces, cambiar colores y aplicar efectos.

Ejemplo Funcional

Aquí hay un ejemplo completo y funcional con valores reales (reemplázalos con los tuyos):

  1. Dispositivo descubierto en: <DEVICE_IP>:16021
  2. Token de autenticación obtenido: <AUTH_TOKEN>
  3. Configuración de Warp:
{
  "mcpServers": {
    "nanoleaf": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "NANOLEAF_IP=<DEVICE_IP>",
        "-e", "NANOLEAF_AUTH_TOKEN=<AUTH_TOKEN>",
        "-e", "NANOLEAF_PORT=16021",
        "-e", "NANOLEAF_PROTOCOL=http",
        "nanoleaf-mcp-server-nanoleaf-mcp-server"
      ],
      "env": {}
    }
  }
}
  1. Comando de prueba:
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "set_effect", "arguments": {"effect": "Cyberpunk 2077"}}}' | docker run --rm -i --network=host -e NANOLEAF_IP=<DEVICE_IP> -e NANOLEAF_AUTH_TOKEN=<AUTH_TOKEN> nanoleaf-mcp-server-nanoleaf-mcp-server

Integración con Terminal Warp

Agregar a la Configuración MCP de Warp

Agrega esto a la configuración de servidores MCP de Warp (reemplaza los valores con la IP real de tu dispositivo y el token de autenticación):

{
  "mcpServers": {
    "nanoleaf": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "NANOLEAF_IP=192.168.1.100",
        "-e", "NANOLEAF_AUTH_TOKEN=YourAuthTokenHere123456789",
        "-e", "NANOLEAF_PORT=16021",
        "-e", "NANOLEAF_PROTOCOL=http",
        "nanoleaf-mcp-server-nanoleaf-mcp-server"
      ],
      "env": {}
    }
  }
}

Importante:

  • Reemplaza 192.168.1.100 con la dirección IP de tu dispositivo Nanoleaf
  • Reemplaza YourAuthTokenHere123456789 con tu token de autenticación real
  • Asegúrate de haber construido la imagen Docker con la etiqueta nanoleaf-mcp-server-nanoleaf-mcp-server

Configuración Alternativa (si hay problemas de ruta)

Si encuentras problemas relacionados con rutas, también puedes usar este enfoque alternativo:

{
  "mcpServers": {
    "nanoleaf": {
      "command": "bash",
      "args": ["-c", "cd /path/to/nanoleaf-mcp-server && docker run --rm -i --network=host --env-file .env nanoleaf-mcp-server-nanoleaf-mcp-server"],
      "env": {}
    }
  }
}

Uso en Warp

Una vez configurado, puedes usar las herramientas de Nanoleaf directamente en Warp:

  • Pide encender/apagar las luces
  • Cambia brillo y colores
  • Aplica efectos geniales como "Northern Lights" o "Cyberpunk"
  • Obtén información del dispositivo

Ejemplos de Uso Manual

Encender/apagar luces

# Turn on
curl -X PUT http://your-ip:16021/api/v1/your-token/state \
  -H "Content-Type: application/json" \
  -d '{"on":{"value":true}}'

# Turn off  
curl -X PUT http://your-ip:16021/api/v1/your-token/state \
  -H "Content-Type: application/json" \
  -d '{"on":{"value":false}}'

Establecer brillo

curl -X PUT http://your-ip:16021/api/v1/your-token/state \
  -H "Content-Type: application/json" \
  -d '{"brightness":{"value":50}}'

Aplicar un efecto

curl -X PUT http://your-ip:16021/api/v1/your-token/effects \
  -H "Content-Type: application/json" \
  -d '{"select":"Northern Lights"}'

Solución de Problemas

Dispositivo No Encontrado

  • Asegúrate de que el dispositivo esté en la misma red
  • Revisa la configuración del firewall
  • Intenta el escaneo manual de IP: nmap -p 16021 192.168.1.0/24

Autorización Fallida

  • El dispositivo debe estar en modo de emparejamiento (mantén presionado el botón de encendido 5-7 segundos)
  • El modo de emparejamiento solo dura ~30 segundos
  • Asegúrate de que ningún otro dispositivo lo esté controlando

Problemas de Conexión

  • Verifica que la dirección IP sea correcta
  • Revisa si el dispositivo usa HTTPS (algunos modelos más nuevos)
  • Asegúrate de que Docker tenga acceso a la red (--network=host)

Variables de Entorno Que No Funcionan

  • Revisa que el archivo .env exista y tenga valores correctos
  • Verifica que el comando Docker incluya --env-file .env
  • Asegúrate de que las rutas de archivo sean absolutas en la configuración de Warp

Problemas con la Terminal Warp

Error "El sistema no puede encontrar la ruta especificada"

  • Usa la configuración directa de variables de entorno en lugar de --env-file
  • Asegúrate de que la etiqueta de tu imagen Docker coincida exactamente: nanoleaf-mcp-server-nanoleaf-mcp-server
  • Prueba la configuración alternativa de bash si los problemas de ruta persisten

El servidor MCP no responde en Warp

  • Verifica que la imagen Docker esté construida con la etiqueta correcta
  • Revisa que tu dirección IP y token de autenticación sean correctos en la configuración
  • Prueba el comando Docker manualmente primero: 
    echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_nanoleaf_info", "arguments": {}}}' | docker run --rm -i --network=host -e NANOLEAF_IP=your-ip -e NANOLEAF_AUTH_TOKEN=your-token nanoleaf-mcp-server-nanoleaf-mcp-server

"El servidor MCP salió" en los registros

  • Esto generalmente indica un problema de configuración
  • Revisa que todas las variables de entorno estén configuradas correctamente
  • Asegúrate de que la imagen Docker exista: docker images | grep nanoleaf

Compatibilidad de Dispositivos

Probado con:

  • Nanoleaf Canvas
  • Nanoleaf Light Panels
  • Nanoleaf Hexagons

Debería funcionar con la mayoría de dispositivos Nanoleaf que soporten la API v1.

Documentación

  • Informe de Auditoría de Dependencias - Auditoría de seguridad detallada e información de actualización de dependencias
  • Scripts de Configuración - Scripts automatizados de configuración y prueba incluidos
  • Configuración Docker - Implementación contenerizada para fácil gestión

Contribuciones

¡Siéntete libre de enviar problemas, solicitudes de funciones o pull requests!

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.