ccu-mcp

ccu-mcp é um servidor Model Context Protocol (MCP) que conecta assistentes de IA (como Claude, Cursor ou qualquer cliente MCP) a sistemas domésticos inteligentes HomeMatic. Ele se conecta diretamente à API JSON-RPC integrada da CCU (via `/api/homematic.cgi`), eliminando a necessidade de addons, XML-API ou serviços em nuvem. Funciona com qualquer HomeMatic CCU, incluindo debmatic, CCU3 e OpenCCU (anteriormente RaspberryMatic). O servidor lida com descoberta de dispositivos, resolução de tipos, gerenciamento de sessão e conversão de valores, expondo ferramentas que permitem aos usuários fazer perguntas em linguagem natural como "Qual é a temperatura no banheiro?", "Alguma janela está aberta?", "Defina o aquecimento da sala para 21 graus" ou "Mostre-me todos os dispositivos com bateria fraca". Também suporta operações avançadas como renomear dispositivos para seguir convenções de nomenclatura, encontrar nomes de canais incompatíveis e verificar a saúde dos dispositivos. **Principais Recursos:** - **Conexão direta com a CCU**: Sem addons ou nuvem; usa o endpoint JSON-RPC padrão. - **Múltiplos transportes**: Execute como subprocesso (stdio) ou como servidor HTTP autônomo (Docker). - **Suporte a Docker**: Imagens publicadas para linux/amd64 e linux/arm64, com atestação para segurança da cadeia de suprimentos. - **Múltiplos perfis CCU**: Configure e alterne entre várias CCUs (ex.: prod e dev) a partir de um único servidor. - **Segurança**: Autenticação por token Bearer (gerado automaticamente ou explícito), proteção contra rebinding de DNS, lista de permissões CORS, suporte a TLS (incluindo pinning de certificados autoassinados) e integração opcional com fail2ban. - **Assistente de configuração**: O comando interativo `init` testa a CCU, fixa certificados TLS, testa o login e escreve um arquivo `.env` pronto para uso. Um modo de configuração conversacional permite que um LLM guie o processo via chat. - **Diagnóstico**: O comando `doctor` valida a configuração de ponta a ponta. - **Limitação de taxa**: Limites de taxa integrados para rajadas e sustentados para proteger a CCU. - **Polling de recursos**: Polling opcional para notificações de mudança de recursos MCP. **Instalação e Uso:** - **Início rápido (stdio)**: Defina as variáveis de ambiente `CCU_HOST` e `CCU_PASSWORD`, depois execute `npx ccu-mcp --stdio`. Configure seu cliente MCP (ex.: Claude Code) com um arquivo `.mcp.json`. - **Docker (HTTP)**: Baixe a imagem, execute com variáveis de ambiente e obtenha o token de autenticação do volume de dados do contêiner. Configure o cliente com a URL do servidor e o token Bearer. - **Configuração**: Todas as configurações via variáveis de ambiente (veja tabela no README). Suporta env inline, arquivos `.env` ou exports de shell. - **Flags CLI**: `init`, `doctor`, `secret`, `--stdio`, `--http`, `--env`, `--version`, `--help`. **Considerações de Segurança:** - O servidor usa HTTP simples por padrão, mas avisa ao servir tokens em interfaces não loopback; defina `MCP_ALLOW_PLAINTEXT=true` para confirmar. - Para acesso remoto, use TLS (proxy reverso ou HTTPS nativo) e defina `MCP_ALLOWED_HOSTS` para evitar erros 403. - A rotação de tokens é suportada com períodos de carência para evitar interrupções no cliente. - CORS é negado por padrão; use lista de permissões para origens de clientes baseados em navegador. **Requisitos:** Node.js 24+ (para fonte/stdio) ou Docker. Uma HomeMatic CCU em execução com credenciais de administrador. **Exemplo de Configuração do Cliente (stdio):** ```json { "mcpServers": { "ccu-mcp": { "command": "npx", "args": ["ccu-mcp", "--stdio"], "env": { "CCU_HOST": "seu-hostname-ou-ip-da-ccu", "CCU_PASSWORD": "sua-senha-de-admin-da-ccu" } } } } ``` **Exemplo de Configuração do Cliente (HTTP):** ```json { "mcpServers": { "ccu-mcp": { "url": "http://seu-ip-do-servidor:3000", "headers": { "Authorization": "Bearer COLE-SEU-TOKEN-AQUI" } } } } ``` O projeto é open-source e aceita contribuições. Inclui selos para OpenSSF Best Practices e Scorecard, indicando foco em segurança e qualidade.