Nanoleaf MCP Server

Um servidor para controlar luzes inteligentes Nanoleaf usando o Model Context Protocol.

GitHubExperimente este MCPPatrocinado

Documentação

Nanoleaf MCP Server

Um servidor Model Context Protocol (MCP) para controlar luzes inteligentes Nanoleaf. Este servidor fornece ferramentas para controlar seus dispositivos Nanoleaf através do terminal Warp ou qualquer cliente compatível com MCP.

Nanoleaf Server MCP server

Recursos

  • 🔍 Descoberta automática de dispositivos Nanoleaf na sua rede
  • 🔗 Conexão IP direta para direcionar dispositivos específicos
  • 🔐 Suporte a autorização para pareamento seguro de dispositivos
  • 💡 Controle total de luzes, brilho, cores e efeitos
  • 🐳 Dockerizado para fácil implantação
  • 🖥️ Integração com terminal Warp
  • 🔒 Dependências com auditoria de segurança e verificações regulares de vulnerabilidades

Ferramentas Disponíveis

  • get_nanoleaf_info - Obter informações detalhadas do dispositivo
  • turn_on_nanoleaf / turn_off_nanoleaf - Controlar o estado de energia
  • set_brightness - Ajustar o brilho (0-100)
  • set_color - Definir a cor usando matiz (0-360) e saturação (0-100)
  • set_effect - Aplicar efeitos de iluminação
  • get_effects - Listar todos os efeitos disponíveis
  • discover_nanoleaf - Descobrir dispositivos na rede
  • connect_to_ip - Conectar a um endereço IP específico
  • authorize_nanoleaf - Autorizar com o dispositivo em modo de pareamento

Guia de Configuração Rápida

Configuração Automatizada (Recomendada)

Para a experiência de configuração mais fácil, use o script de configuração incluso:

./setup.sh

Este script irá:

  1. Construir a imagem Docker
  2. Procurar dispositivos Nanoleaf na sua rede
  3. Ajudar você a obter o token de autorização
  4. Criar todos os arquivos de configuração
  5. Testar a configuração
  6. Gerar sua configuração do Warp

Configuração Manual

Pré-requisitos

  • Docker instalado no seu sistema
  • Dispositivo(s) Nanoleaf na sua rede
  • Terminal Warp (opcional, para integração com MCP)

Passo 1: Clonar e Construir

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

Passo 2: Encontrar Seu Dispositivo Nanoleaf

Opção A: Descoberta automática

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

Opção B: Verificação manual de IP

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

Opção C: Verificar o painel administrativo do roteador para dispositivos conectados

Passo 3: Obter o Token de Autorização

  1. Coloque seu dispositivo Nanoleaf em modo de pareamento:

    • Segure o botão de energia do seu dispositivo Nanoleaf por 5 a 7 segundos
    • Procure pelo indicador de pareamento (geralmente uma luz piscando)

  2. Obtenha o token de autorização imediatamente (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

    Você deve receber uma resposta como:

    {"auth_token":"YourAuthTokenHere123456789"}

Passo 4: Configurar o Ambiente

Crie um arquivo .env no diretório do projeto:

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

Passo 5: Testar Sua Configuração

# 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": {}}}'

Se for bem-sucedido, você verá informações detalhadas sobre seu dispositivo Nanoleaf!

Passo 6: Executar Exemplos (Opcional)

Teste todas as funcionalidades com o script de exemplo:

./examples.sh

Isso demonstrará todos os recursos disponíveis, incluindo ligar/desligar luzes, alterar cores e aplicar efeitos.

Exemplo Funcional

Aqui está um exemplo completo e funcional com valores reais (substitua pelos seus):

  1. Dispositivo descoberto em: <DEVICE_IP>:16021
  2. Token de autorização obtido: <AUTH_TOKEN>
  3. Configuração do 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 teste:
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

Integração com Terminal Warp

Adicionar à Configuração MCP do Warp

Adicione isto à configuração dos servidores MCP do Warp (substitua os valores pelo IP real do seu dispositivo e token de autorização):

{
  "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:

  • Substitua 192.168.1.100 pelo endereço IP do seu dispositivo Nanoleaf
  • Substitua YourAuthTokenHere123456789 pelo seu token de autorização real
  • Certifique-se de que você construiu a imagem Docker com a tag nanoleaf-mcp-server-nanoleaf-mcp-server

Configuração Alternativa (se houver problemas de caminho)

Se você encontrar problemas relacionados a caminhos, também pode usar esta abordagem alternativa:

{
  "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 no Warp

Após a configuração, você pode usar as ferramentas Nanoleaf diretamente no Warp:

  • Peça para ligar/desligar as luzes
  • Alterar brilho e cores
  • Aplicar efeitos legais como "Northern Lights" ou "Cyberpunk"
  • Obter informações do dispositivo

Exemplos de Uso Manual

Ligar/desligar luzes

# 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}}'

Definir brilho

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

Aplicar um efeito

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

Solução de Problemas

Dispositivo Não Encontrado

  • Certifique-se de que o dispositivo está na mesma rede
  • Verifique as configurações do firewall
  • Tente a verificação manual de IP: nmap -p 16021 192.168.1.0/24

Falha na Autorização

  • O dispositivo deve estar em modo de pareamento (segure o botão de energia por 5 a 7 segundos)
  • O modo de pareamento dura apenas ~30 segundos
  • Certifique-se de que nenhum outro dispositivo já está controlando-o

Problemas de Conexão

  • Verifique se o endereço IP está correto
  • Confira se o dispositivo usa HTTPS (alguns modelos mais novos)
  • Garanta que o Docker tem acesso à rede (--network=host)

Variáveis de Ambiente Não Funcionando

  • Verifique se o arquivo .env existe e tem os valores corretos
  • Confirme que o comando Docker inclui --env-file .env
  • Certifique-se de que os caminhos dos arquivos são absolutos na configuração do Warp

Problemas com o Terminal Warp

Erro "The system cannot find the path specified"

  • Use a configuração direta de variáveis de ambiente em vez de --env-file
  • Certifique-se de que a tag da sua imagem Docker corresponde exatamente: nanoleaf-mcp-server-nanoleaf-mcp-server
  • Tente a configuração bash alternativa se os problemas de caminho persistirem

Servidor MCP não respondendo no Warp

  • Verifique se a imagem Docker foi construída com a tag correta
  • Confirme se o endereço IP e o token de autorização estão corretos na configuração
  • Teste o comando Docker manualmente primeiro: 
    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

"MCP server exited" nos logs

  • Isso geralmente indica um problema de configuração
  • Verifique se todas as variáveis de ambiente estão definidas corretamente
  • Garanta que a imagem Docker existe: docker images | grep nanoleaf

Compatibilidade de Dispositivos

Testado com:

  • Nanoleaf Canvas
  • Nanoleaf Light Panels
  • Nanoleaf Hexagons

Deve funcionar com a maioria dos dispositivos Nanoleaf que suportam a API v1.

Documentação

  • Relatório de Auditoria de Dependências - Auditoria de segurança detalhada e informações sobre atualizações de dependências
  • Scripts de Configuração - Scripts automatizados de configuração e teste incluídos
  • Configuração Docker - Implantação conteinerizada para fácil gerenciamento

Contribuindo

Sinta-se à vontade para enviar issues, solicitações de recursos ou pull requests!

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.