netatmo-energy-mcp
Termostatos e válvulas de radiador Netatmo para assistentes de IA: status, histórico, análises e controle seguro.
Documentação
Netatmo Energy MCP
Português | Français
Um servidor MCP Netatmo para termostatos inteligentes e válvulas de radiador inteligentes da Netatmo. Ele dá aos assistentes de IA acesso estruturado ao seu aquecimento:
- temperaturas e setpoints dos ambientes
- demanda de aquecimento e atividade da caldeira
- histórico de temperaturas
- análises determinísticas de aquecimento
- programações semanais de aquecimento
- controle opcional de aquecimento: setpoints dos ambientes, modo ausente / proteção contra geada e programações, com cada alteração confirmada por você
Ele roda na sua máquina e fala apenas com a API oficial Netatmo Energy. Ele é somente leitura por padrão: só pode alterar seu aquecimento se você habilitar o modo de escrita no login.
Ele funciona com qualquer cliente Model Context Protocol que execute servidores locais, independentemente do modelo:
- Claude: Claude Desktop, Claude Code
- GPT / OpenAI: Codex CLI, VS Code + GitHub Copilot, Cursor
- Gemini: Gemini CLI, VS Code + GitHub Copilot
- Mistral e outros por meio de clientes multimodelo
- LLMs locais (Llama, Qwen, Mistral, DeepSeek, …): LM Studio e Ollama via Goose, Continue, Cline, AnythingLLM, LibreChat ou Open WebUI
Ele também funciona em Windsurf / Devin Desktop, Zed, Roo Code, Kilo Code, JetBrains AI Assistant, Kiro e Warp. Veja todos os clientes compatíveis.
ChatGPT e Claude na web e no celular aceitam apenas servidores remotos. Para eles, implante o servidor remoto opcional na sua própria conta Cloudflare (plano gratuito).
Status: versão inicial (0.3.1). A integração com a API Netatmo foi validada em uma instalação real; feedback e relatos de dispositivos são bem-vindos.
Por que este projeto?
Um sistema de aquecimento Netatmo registra dados úteis:
- a temperatura e o setpoint de cada ambiente
- o que cada válvula de radiador está solicitando
- quando a caldeira é acionada para aquecer
Esses dados ficam presos no aplicativo Netatmo, onde você pode vê-los, mas não fazer perguntas sobre eles.
Este projeto é uma pequena ponte entre a API Netatmo Energy e qualquer assistente de IA compatível com MCP. Pergunte em linguagem natural: "Qual ambiente ficou mais frio ontem à noite?" O assistente chama uma ferramenta precisa e responde com base nos seus dados. Ele não adivinha. Com o modo de escrita habilitado, você também pode dizer "Defina o quarto para 19 °C até as 7h" e depois confirmar a alteração.
Os poucos outros servidores MCP Netatmo visam estações meteorológicas da Netatmo. Este foi criado para termostatos, válvulas de radiador e histórico de aquecimento. Veja docs/research.md para a comparação.
Recursos
- Descoberta: residências, ambientes, termostatos, válvulas de radiador inteligentes, relés e gateways.
- Status atual
- Por ambiente: temperatura, setpoint, modo do setpoint e demanda de aquecimento.
- Caldeira ligada/desligada e detecção de janela aberta.
- Saúde do dispositivo: bateria, sinal de rádio/Wi-Fi, acessibilidade.
- Histórico
- Histórico de temperatura e setpoint dos ambientes com resolução de 30 minutos a 1 mês.
- Histórico de atividade da caldeira (instalações com termostato Netatmo).
- Intervalos longos são buscados em blocos e resumidos, para que as respostas permaneçam pequenas.
- Lacunas são relatadas, nunca preenchidas.
- Análises de aquecimento. São cálculos determinísticos; nenhum modelo
de IA calcula os números.
- Estatísticas por ambiente.
- Tempo abaixo, dentro ou acima do setpoint.
- Maior queda de temperatura e taxas de resfriamento.
- Rankings dos ambientes.
- Detecção baseada em regras de leituras incomuns, cada uma com gravidade e confiança.
- Programações semanais: zonas (Conforto, Noite, Eco…), setpoints dos ambientes por zona e o cronograma, como dias e horários legíveis.
- Controle de aquecimento (modo de escrita opcional)
- Setpoints temporários dos ambientes que sempre terminam (3 h por padrão, no máximo 24 h) ou retorno à programação.
- Modo da residência: programação, ausente ou proteção contra geada, opcionalmente até uma data.
- Alternar, criar, editar e renomear programações semanais.
- Cada alteração é pré-visualizada e precisa da sua confirmação explícita. As temperaturas são limitadas a 7–28 °C por padrão.
- 15 ferramentas MCP somente leitura, 6 ferramentas de controle de aquecimento, 4 recursos e 4 prompts (relatório diário, revisão de anomalias, comparação de ambientes, revisão do padrão de aquecimento).
- Configuração simples
- Login OAuth2 no navegador com um único comando
login. - Tokens armazenados com segurança e atualizados automaticamente.
doctorverifica sua configuração.
- Login OAuth2 no navegador com um único comando
Início rápido
Você precisa do Node.js 22.19 ou posterior e de uma conta Netatmo com dispositivos Energy.
1. Crie um aplicativo de desenvolvedor Netatmo gratuito
- Em https://dev.netatmo.com/apps, escolha Criar.
- Defina o URI de redirecionamento para
http://localhost:8977/callback. - Guarde o ID do cliente e o segredo do cliente para o passo 2.
Guia passo a passo: docs/authentication.md.
2. Faça login
npx -y netatmo-energy-mcp login
login solicita o ID e o segredo do cliente e, em seguida, abre seu navegador para que você
possa entrar em netatmo.com e aprovar o acesso somente leitura. Para permitir que o
assistente altere seu aquecimento, execute login --write (veja
modo de escrita). Depois, verifique a configuração:
npx -y netatmo-energy-mcp doctor
Executando a partir do código-fonte: clone o repositório, execute
pnpm install && pnpm builde usenode /path/to/netatmo-energy-mcp/dist/index.jsno lugar denpx -y netatmo-energy-mcp.
3. Conecte seu assistente de IA
A maioria dos clientes usa o mesmo bloco JSON mcpServers. Isso funciona para Claude
Desktop, Cursor, Windsurf / Devin Desktop, Cline, Roo Code, Kiro,
LM Studio, JetBrains AI Assistant, AnythingLLM, Warp e Gemini CLI:
{
"mcpServers": {
"netatmo-energy": {
"command": "npx",
"args": ["-y", "netatmo-energy-mcp"]
}
}
}
Clientes de linha de comando:
# Claude Code
claude mcp add --transport stdio --scope user netatmo-energy -- npx -y netatmo-energy-mcp
# OpenAI Codex CLI
codex mcp add netatmo-energy -- npx -y netatmo-energy-mcp
# GitHub Copilot CLI
copilot mcp add netatmo-energy -- npx -y netatmo-energy-mcp
VS Code + GitHub Copilot. Adicione isso a .vscode/mcp.json; observe a
chave servers:
{
"servers": {
"netatmo-energy": { "type": "stdio", "command": "npx", "args": ["-y", "netatmo-energy-mcp"] }
}
}
Nenhum segredo vai em nenhum desses arquivos: login os armazenou na sua pasta de
configuração do usuário. Os locais dos arquivos para cada cliente, além de Zed,
Continue, Goose, LibreChat, Kilo Code, Msty e Open WebUI, estão em
examples/.
4. Pergunte
"Qual é a temperatura em cada ambiente agora?"
Exemplos de perguntas
Estes são os tipos de perguntas para as quais as ferramentas foram criadas. O assistente escolhe as ferramentas; a tabela mostra quais respondem a cada pergunta.
| Pergunta | Ferramentas usadas |
|---|---|
| "Qual é a temperatura no meu quarto e está na meta?" | netatmo_get_room_status |
| "A caldeira está funcionando agora? Quais ambientes estão pedindo calor?" | netatmo_get_heating_status |
| "Por quanto tempo minha caldeira funcionou ontem?" | netatmo_get_boiler_history |
| "Mostre a temperatura da sala de estar nos últimos 7 dias." | netatmo_get_temperature_history |
| "Compare meus ambientes na última semana. Qual esfria mais rápido?" | netatmo_compare_rooms |
| "Meu aquecimento se comportou de forma incomum ontem à noite?" | netatmo_detect_anomalies |
| "Me dê o relatório de aquecimento de ontem." | prompt heating_daily_report → netatmo_get_heating_summary |
| "Alguma bateria de válvula está fraca?" | netatmo_get_device_status |
| "Como está minha programação semanal?" | netatmo_get_schedules |
| Modo de escrita: "Aqueça o escritório a 21 °C por 2 horas." | netatmo_set_room_setpoint |
| Modo de escrita: "Estou fora até domingo à noite." | netatmo_set_home_mode |
| Modo de escrita: "Reduza a zona noturna para 17 °C em todos os quartos." | netatmo_get_schedules → netatmo_update_schedule |
O "tempo de funcionamento" da caldeira é o tempo em que o termostato solicitou calor. A Netatmo não mede consumo de gás ou energia, então este projeto nunca o relata.
Ferramentas MCP disponíveis
As ferramentas somente leitura precisam apenas do escopo OAuth read_thermostat. A referência
completa, com argumentos e saídas, é gerada a partir do próprio servidor:
docs/tools.md.
| Ferramenta | Descrição |
|---|---|
netatmo_list_homes | Residências com dispositivos Energy, contagens de ambientes/dispositivos |
netatmo_get_home | Detalhes da residência: modo de aquecimento, programações, ambientes, dispositivos |
netatmo_list_rooms | Ambientes com IDs, tipos e dispositivos |
netatmo_list_devices | Termostatos, válvulas, relés: modelo, ambiente, gateway |
netatmo_get_home_status | Status atual de cada ambiente, estado da caldeira, alertas |
netatmo_get_room_status | Temperatura e setpoint atuais de um ambiente |
netatmo_get_heating_status | Caldeira ligada/desligada, ambientes solicitando calor |
netatmo_get_device_status | Bateria, sinal, acessibilidade, firmware |
netatmo_get_temperature_history | Histórico de temperatura do ambiente com estatísticas e lacunas |
netatmo_get_setpoint_history | Histórico de setpoint do ambiente e períodos de setpoint |
netatmo_get_boiler_history | Tempo de demanda de calor da caldeira por hora/dia/semana |
netatmo_get_heating_summary | Métricas de conforto por ambiente e tempo de caldeira em um período |
netatmo_compare_rooms | Métricas e rankings dos ambientes |
netatmo_detect_anomalies | Leituras incomuns com gravidade, confiança e evidências |
netatmo_get_schedules | Programações semanais: zonas, setpoints dos ambientes, cronograma |
Somente modo de escrita. Cada alteração precisa da sua confirmação.
| Ferramenta | Descrição |
|---|---|
netatmo_set_room_setpoint | Setpoint temporário do ambiente ou impulso, ou retorno à programação |
netatmo_set_home_mode | Modo programação, ausente ou proteção contra geada, opcionalmente até uma data |
netatmo_switch_schedule | Ativar outra programação semanal |
netatmo_create_schedule | Nova programação copiada de uma existente, com alterações |
netatmo_update_schedule | Setpoints dos ambientes por zona, temperaturas de ausente/geada, cronograma |
netatmo_rename_schedule | Renomear uma programação (experimental: endpoint não documentado) |
Recursos: netatmo://homes e netatmo://homes/{homeId}/rooms,
…/devices e …/status.
Modo de escrita (controle de aquecimento)
O modo de escrita está desativado por padrão. Para ativá-lo, faça login novamente com:
npx -y netatmo-energy-mcp login --write
Isso também solicita o escopo OAuth write_thermostat. As ferramentas de controle
de aquecimento aparecem após você reiniciar seu cliente MCP.
Proteções:
- Você confirma cada alteração. Clientes que suportam elicitação MCP perguntam
diretamente a você. Com outros clientes, a primeira chamada retorna apenas uma pré-visualização
e um token de uso único. O assistente deve mostrar a pré-visualização e obter seu
consentimento antes de chamar novamente. Nada é enviado à Netatmo antes
disso. Esse segundo fluxo depende de o assistente seguir suas
instruções; defina
NETATMO_MCP_CONFIRM=elicitationpara permitir alterações apenas por meio de um prompt de confirmação exibido pelo seu cliente. Se o seu cliente cancelar cada alteração sem mostrar nada, definaNETATMO_MCP_CONFIRM=token. - Limites. As temperaturas devem permanecer entre 7 e 28 °C. Setpoints manuais
terminam após 3 h por padrão e 24 h no máximo. Altere-os com
NETATMO_MCP_MIN_TEMP,NETATMO_MCP_MAX_TEMPeNETATMO_MCP_MAX_SETPOINT_HOURS. - Interruptor de emergência.
NETATMO_MCP_WRITE=0força o modo somente leitura, mesmo com um login habilitado para escrita. - Log de auditoria. Cada alteração aplicada ou falha é anexada a
changes.logna sua pasta de configuração. - Sem novas tentativas automáticas. Uma escrita falha nunca é reenviada às cegas. A Netatmo não possui API para excluir um cronograma: cronogramas criados aqui só podem ser excluídos no aplicativo Netatmo. Renomear um cronograma e escolher um cronograma com o modo "cronograma" da casa usam parâmetros Netatmo não documentados, portanto são marcados como experimentais. Detalhes: docs/configuration.md.
Web e mobile (servidor remoto)
O servidor local é a opção mais simples e privada. Para usar seu aquecimento pelo ChatGPT ou Claude na web e no celular, implante as mesmas ferramentas como um servidor remoto na sua própria conta Cloudflare (plano gratuito): remote/README.md.
- Mesmas ferramentas e proteções. Somente leitura por padrão; modo de escrita com pré-visualizações, confirmações e os mesmos limites.
- Seus segredos permanecem na sua conta. Suas credenciais e tokens do aplicativo Netatmo são criptografados em repouso na sua conta Cloudflare.
- Assistentes entram com OAuth. Você aprova cada um em uma página de consentimento com sua senha de proprietário e pode revogá-lo.
- Um comando para vincular sua casa:
npx netatmo-energy-mcp remote setup <your-worker-url>. - Opcional: permita que familiares ou amigos conectem suas próprias contas Netatmo com um código de convite (
ONBOARDING=invite). Cada conta vê apenas a própria casa.
O fluxo de login foi validado com ChatGPT (desktop e mobile) e Claude (web, desktop e mobile). Design: ADR-0013, ADR-0014.
Dispositivos suportados
| Dispositivo | Tipo Netatmo | Status |
|---|---|---|
| Termostato Inteligente | NATherm1 | Testado. API validada em uma instalação real (2026-10-08) |
| Válvula Inteligente para Radiador | NRV | Testado. Mesma instalação (6 válvulas) |
| Relé do Termostato | NAPlug | Testado. Mesma instalação |
| Termostato Modulante OpenTherm / Gateway | OTM / OTH | Esperado para funcionar, não testado |
| BTicino Smarther com Netatmo | BNS | Não suportado na v0.1 (provavelmente precisa do escopo read_smarther) |
Execute netatmo-energy-mcp probe e abra um relatório de compatibilidade de dispositivos para ajudar a expandir esta tabela. A saída da sondagem é sanitizada.
Assistentes de IA e clientes MCP compatíveis
Este é um servidor MCP local (stdio) padrão, portanto não está vinculado a um fornecedor de IA. Qualquer cliente MCP que possa iniciar servidores locais pode usá-lo, com qualquer modelo que esse cliente execute.
| Cliente | Modelos |
|---|---|
| Claude Desktop, Claude Code | Claude |
| OpenAI Codex CLI | Modelos OpenAI GPT |
| Gemini CLI | Google Gemini |
| VS Code + GitHub Copilot (modo agente), GitHub Copilot CLI | GPT, Claude, Gemini e outros modelos Copilot |
| Cursor, Windsurf / Devin Desktop, Zed, Warp, Kiro, JetBrains AI Assistant | múltiplos modelos hospedados |
| Cline, Roo Code, Kilo Code, Continue | múltiplos, incluindo modelos locais (Ollama, LM Studio) |
| LM Studio | modelos abertos locais: Llama, Qwen, Mistral, DeepSeek, … |
| Goose, AnythingLLM, LibreChat, Msty Studio | muitos provedores, incluindo Ollama |
| Open WebUI | Ollama e outros, através do proxy mcpo |
Configuração para cada cliente, verificada com a documentação oficial: examples/.
Assistentes web e mobile (aplicativos e conectores ChatGPT, Claude.ai e os aplicativos mobile Claude e ChatGPT) aceitam apenas servidores MCP remotos. Use o servidor remoto para eles. O Mistral Le Chat não foi testado.
Testes. O servidor é testado com o cliente oficial do SDK MCP e o MCP Inspector. A qualidade de chamada de ferramentas com modelos locais pequenos varia conforme o modelo. Por favor, relate qualquer problema específico de cliente.
Autenticação
Este projeto usa o fluxo de código de autorização OAuth2 da Netatmo. Você faz login em netatmo.com; sua senha Netatmo nunca é vista por esta ferramenta.
Escopo. Por padrão, apenas read_thermostat é solicitado, então um token vazado não poderia alterar seu aquecimento. login --write também solicita write_thermostat.
Seu próprio aplicativo. Cada usuário registra um aplicativo de desenvolvedor Netatmo gratuito. O segredo do cliente não pode ser embarcado em código de código aberto.
Atualização. Os tokens de acesso são atualizados automaticamente. Vários clientes MCP rodando ao mesmo tempo se coordenam por meio de um arquivo de bloqueio, para não invalidarem os tokens uns dos outros.
Detalhes: docs/authentication.md.
Privacidade e segurança
O que sai da sua máquina. Apenas solicitações HTTPS para api.netatmo.com. No modo somente leitura, elas alcançam apenas 4 endpoints de leitura: o cliente recusa qualquer escrita antes de tocar a rede, e os testes garantem isso. No modo de escrita, uma alteração é enviada somente após você confirmá-la.
O que permanece local.
- As credenciais ficam em
credentials.jsonna sua pasta de configuração do usuário, legíveis apenas pela sua conta (0600no macOS/Linux; uma ACL restrita no Windows). - Sem telemetria, sem análises e sem serviços de terceiros.
- O servidor conversa com seu cliente MCP via stdio e não abre porta de rede.
Seu provedor de IA. Os dados retornados pelas ferramentas são lidos pelo assistente que você usa, portanto são processados pelo provedor desse modelo.
Sem dados de conta ou localização. Seu e-mail e coordenadas da casa nunca são retornados.
Leia mais:
Arquitetura
O cliente Netatmo e as análises são independentes do MCP. As decisões de design são registradas como ADRs, e docs/architecture.md descreve as camadas.
Limitações
Elas vêm da API Netatmo Energy; detalhes em docs/api-capabilities.md.
- Sem consumo de energia ou gás. A atividade da caldeira é tempo de demanda de calor. Com dados agregados, o número de ciclos do queimador não pode ser conhecido.
- Sem histórico de demanda de aquecimento das válvulas. Está disponível apenas como valor atual. Um coletor opcional futuro pode registrá-lo (ADR-0011).
- Sem temperatura externa na API Energy. O contexto meteorológico está planejado para a v0.4.
- A resolução do histórico é de 30 minutos no máximo. Cada solicitação retorna no máximo 1024 valores, então intervalos longos usam escalas mais grosseiras.
- A documentação não corresponde à API em alguns pontos. Dados ao vivo mostram que as medidas da caldeira estão em segundos, não nos minutos documentados. Este projeto as converte.
- Limites de taxa. A Netatmo limita solicitações por usuário e por aplicativo. O servidor se autorregula e armazena em cache a topologia e o status atual.
Roadmap
| Versão | Foco |
|---|---|
| v0.1 | Servidor MCP somente leitura |
| v0.2 | Cronogramas, controle de aquecimento opcional |
| v0.3 | Servidor remoto para web e mobile (atual) |
| v0.3.x | Diagnósticos mais ricos |
| v0.4 | Contexto meteorológico (Open-Meteo) |
| v0.5–v0.7 | Modelagem térmica, previsões, gêmeo digital |
| v1.0 | Uma interface estável |
O modo de escrita nunca será habilitado por padrão. Veja docs/roadmap.md.
Contribuindo
Relatórios de bugs, relatórios de compatibilidade de dispositivos e pull requests são bem-vindos. Veja CONTRIBUTING.md para configurar o projeto, que roda com respostas de API simuladas: nenhuma conta Netatmo é necessária. Por favor, siga o Código de Conduta.
Licença
Aviso legal
Este é um projeto independente de código aberto. Não é afiliado, endossado ou patrocinado pela Netatmo ou Legrand. "Netatmo" é uma marca registrada de seu proprietário e é usada aqui apenas para descrever compatibilidade. Use por sua conta e risco; a segurança do aquecimento nunca deve depender de um assistente de IA.