netatmo-energy-mcp
Termostatos y válvulas de radiador Netatmo para asistentes de IA: estado, historial, análisis y control seguro.
Documentación
Netatmo Energy MCP
Español | Français
Un servidor MCP de Netatmo para termostatos inteligentes y válvulas de radiador inteligentes de Netatmo. Proporciona a los asistentes de IA acceso estructurado a tu calefacción:
- temperaturas y consignas de las habitaciones
- demanda de calefacción y actividad de la caldera
- historial de temperaturas
- análisis de calefacción deterministas
- programaciones semanales de calefacción
- control opcional de la calefacción: consignas de habitación, modo ausente / protección antihielo y programaciones, con cada cambio confirmado por ti
Se ejecuta en tu máquina y solo se comunica con la API oficial de Netatmo Energy. Es de solo lectura por defecto: solo puede cambiar tu calefacción si habilitas el modo de escritura al iniciar sesión.
Funciona con cualquier cliente de Model Context Protocol que ejecute servidores locales, independientemente del modelo:
- Claude: Claude Desktop, Claude Code
- GPT / OpenAI: Codex CLI, VS Code + GitHub Copilot, Cursor
- Gemini: Gemini CLI, VS Code + GitHub Copilot
- Mistral y otros a través de clientes multimodelo
- LLMs locales (Llama, Qwen, Mistral, DeepSeek, …): LM Studio, y Ollama a través de Goose, Continue, Cline, AnythingLLM, LibreChat o Open WebUI
También funciona en Windsurf / Devin Desktop, Zed, Roo Code, Kilo Code, JetBrains AI Assistant, Kiro y Warp. Consulta todos los clientes compatibles.
ChatGPT y Claude en la web y en móvil solo aceptan servidores remotos. Para ellos, despliega el servidor remoto opcional en tu propia cuenta de Cloudflare (plan gratuito).
Estado: versión preliminar (0.3.1). La integración con la API de Netatmo se ha validado en una instalación real; se agradecen comentarios e informes de dispositivos.
¿Por qué este proyecto?
Un sistema de calefacción Netatmo registra datos útiles:
- la temperatura y la consigna de cada habitación
- lo que solicita cada válvula de radiador
- cuándo se pide a la caldera que caliente
Esos datos están bloqueados en la aplicación Netatmo, donde puedes verlos pero no hacer preguntas sobre ellos.
Este proyecto es un pequeño puente entre la API de Netatmo Energy y cualquier asistente de IA compatible con MCP. Pregunta en lenguaje natural: "¿Qué habitación estuvo más fría anoche?" El asistente llama a una herramienta precisa y responde con tus datos. No adivina. Con el modo de escritura habilitado, también puedes decir "Pon el dormitorio a 19 °C hasta las 7 am" y luego confirmar el cambio.
Los pocos servidores MCP de Netatmo existentes se centran en las estaciones meteorológicas de Netatmo. Este está diseñado para termostatos, válvulas de radiador e historial de calefacción. Consulta docs/research.md para la comparación.
Características
- Descubrimiento: hogares, habitaciones, termostatos, válvulas de radiador inteligentes, relés y pasarelas.
- Estado actual
- Por habitación: temperatura, consigna, modo de consigna y demanda de calefacción.
- Caldera encendida/apagada y detección de ventana abierta.
- Salud del dispositivo: batería, señal de radio/Wi-Fi, accesibilidad.
- Historial
- Historial de temperatura y consigna de la habitación con resolución de 30 minutos a 1 mes.
- Historial de actividad de la caldera (instalaciones con termostato Netatmo).
- Los rangos largos se obtienen en fragmentos y se resumen, para que las respuestas sigan siendo pequeñas.
- Las lagunas se informan, nunca se rellenan.
- Análisis de calefacción. Son cálculos deterministas; ningún modelo
de IA calcula los números.
- Estadísticas por habitación.
- Tiempo por debajo, dentro o por encima de la consigna.
- Mayor caída de temperatura y tasas de enfriamiento.
- Clasificaciones de habitaciones.
- Detección basada en reglas de lecturas inusuales, cada una con gravedad y confianza.
- Programaciones semanales: zonas (Confort, Noche, Eco…), consignas de habitación por zona y el horario, como días y horas legibles.
- Control de calefacción (modo de escritura opcional)
- Consignas temporales de habitación que siempre terminan (3 h por defecto, como máximo 24 h), o un retorno a la programación.
- Modo hogar: programación, ausente o protección antihielo, opcionalmente hasta una fecha.
- Cambiar, crear, editar y renombrar programaciones semanales.
- Cada cambio se previsualiza y necesita tu confirmación explícita. Las temperaturas están limitadas a 7–28 °C por defecto.
- 15 herramientas MCP de solo lectura, 6 herramientas de control de calefacción, 4 recursos y 4 avisos (informe diario, revisión de anomalías, comparación de habitaciones, revisión de patrones de calefacción).
- Configuración sencilla
- Inicio de sesión OAuth2 en el navegador con un solo comando
login. - Tokens almacenados de forma segura y renovados automáticamente.
doctorverifica tu configuración.
- Inicio de sesión OAuth2 en el navegador con un solo comando
Inicio rápido
Necesitas Node.js 22.19 o posterior y una cuenta de Netatmo con dispositivos Energy.
1. Crea una aplicación gratuita de desarrollador de Netatmo
- En https://dev.netatmo.com/apps, elige Crear.
- Establece la URI de redirección a
http://localhost:8977/callback. - Guarda el ID de cliente y el secreto de cliente para el paso 2.
Guía paso a paso: docs/authentication.md.
2. Inicia sesión
npx -y netatmo-energy-mcp login
login solicita el ID y el secreto de cliente, luego abre tu
navegador para que inicies sesión en netatmo.com y apruebes el acceso de
solo lectura. Para permitir que el asistente cambie tu calefacción,
ejecuta login --write en su lugar (consulta
modo de escritura). Luego verifica la configuración:
npx -y netatmo-energy-mcp doctor
Ejecutar desde el código fuente en su lugar: clona el repositorio, ejecuta
pnpm install && pnpm build, y luego usanode /path/to/netatmo-energy-mcp/dist/index.jsen lugar denpx -y netatmo-energy-mcp.
3. Conecta tu asistente de IA
La mayoría de los clientes usan el mismo bloque JSON mcpServers.
Esto funciona para Claude Desktop, Cursor, Windsurf / Devin Desktop,
Cline, Roo Code, Kiro, LM Studio, JetBrains AI Assistant, AnythingLLM,
Warp y Gemini CLI:
{
"mcpServers": {
"netatmo-energy": {
"command": "npx",
"args": ["-y", "netatmo-energy-mcp"]
}
}
}
Clientes de línea de comandos:
# 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. Añade esto a .vscode/mcp.json; ten en
cuenta la clave servers:
{
"servers": {
"netatmo-energy": { "type": "stdio", "command": "npx", "args": ["-y", "netatmo-energy-mcp"] }
}
}
No se guardan secretos en ninguno de estos archivos: login los
almacenó en tu carpeta de configuración de usuario. Las ubicaciones de
archivos para cada cliente, además de Zed, Continue, Goose, LibreChat,
Kilo Code, Msty y Open WebUI, están en examples/.
4. Pregunta
"¿Cuál es la temperatura en cada habitación ahora mismo?"
Preguntas de ejemplo
Estos son los tipos de preguntas para las que están diseñadas las herramientas. El asistente elige las herramientas; la tabla muestra cuáles responden a cada pregunta.
| Pregunta | Herramientas utilizadas |
|---|---|
| "¿Cuál es la temperatura en mi dormitorio, y está en su objetivo?" | netatmo_get_room_status |
| "¿Está funcionando la caldera ahora? ¿Qué habitaciones piden calor?" | netatmo_get_heating_status |
| "¿Cuánto tiempo funcionó mi caldera ayer?" | netatmo_get_boiler_history |
| "Muestra la temperatura del salón de los últimos 7 días." | netatmo_get_temperature_history |
| "Compara mis habitaciones durante la última semana. ¿Cuál se enfría más rápido?" | netatmo_compare_rooms |
| "¿Se comportó mi calefacción de forma inusual anoche?" | netatmo_detect_anomalies |
| "Dame el informe de calefacción de ayer." | aviso heating_daily_report → netatmo_get_heating_summary |
| "¿Hay alguna batería de válvula baja?" | netatmo_get_device_status |
| "¿Cómo es mi programación semanal?" | netatmo_get_schedules |
| Modo de escritura: "Calienta la oficina a 21 °C durante 2 horas." | netatmo_set_room_setpoint |
| Modo de escritura: "Estoy fuera hasta el domingo por la noche." | netatmo_set_home_mode |
| Modo de escritura: "Baja la zona nocturna a 17 °C en cada dormitorio." | netatmo_get_schedules → netatmo_update_schedule |
El "tiempo de funcionamiento" de la caldera es el tiempo que el termostato solicitó calor. Netatmo no mide el consumo de gas o energía, por lo que este proyecto nunca lo informa.
Herramientas MCP disponibles
Las herramientas de solo lectura solo necesitan el alcance OAuth
read_thermostat. La referencia completa, con argumentos y salidas, se
genera desde el propio servidor: docs/tools.md.
| Herramienta | Descripción |
|---|---|
netatmo_list_homes | Hogares con dispositivos Energy, recuentos de habitaciones/dispositivos |
netatmo_get_home | Detalles del hogar: modo de calefacción, programaciones, habitaciones, dispositivos |
netatmo_list_rooms | Habitaciones con IDs, tipos y dispositivos |
netatmo_list_devices | Termostatos, válvulas, relés: modelo, habitación, pasarela |
netatmo_get_home_status | Estado actual de cada habitación, estado de la caldera, alertas |
netatmo_get_room_status | Temperatura y consigna actuales de una habitación |
netatmo_get_heating_status | Caldera encendida/apagada, habitaciones que piden calor |
netatmo_get_device_status | Batería, señal, accesibilidad, firmware |
netatmo_get_temperature_history | Historial de temperatura de la habitación con estadísticas y lagunas |
netatmo_get_setpoint_history | Historial de consignas de la habitación y períodos de consigna |
netatmo_get_boiler_history | Tiempo de demanda de calor de la caldera por hora/día/semana |
netatmo_get_heating_summary | Métricas de confort por habitación más tiempo de caldera en un período |
netatmo_compare_rooms | Métricas y clasificaciones de habitaciones |
netatmo_detect_anomalies | Lecturas inusuales con gravedad, confianza y evidencia |
netatmo_get_schedules | Programaciones semanales: zonas, consignas de habitación, horario |
Solo modo de escritura. Cada cambio necesita tu confirmación.
| Herramienta | Descripción |
|---|---|
netatmo_set_room_setpoint | Consigna temporal de habitación o impulso, o volver a la programación |
netatmo_set_home_mode | Modo programación, ausente o protección antihielo, opcionalmente hasta una fecha |
netatmo_switch_schedule | Activar otra programación semanal |
netatmo_create_schedule | Nueva programación copiada de una existente, con cambios |
netatmo_update_schedule | Consignas de habitación por zona, temperaturas de ausencia/antihielo, horario |
netatmo_rename_schedule | Renombrar una programación (experimental: endpoint no documentado) |
Recursos: netatmo://homes y netatmo://homes/{homeId}/rooms,
…/devices y …/status.
Modo de escritura (control de calefacción)
El modo de escritura está desactivado por defecto. Para habilitarlo, inicia sesión de nuevo con:
npx -y netatmo-energy-mcp login --write
Esto también solicita el alcance OAuth write_thermostat. Las herramientas
de control de calefacción aparecen después de reiniciar tu cliente MCP.
Salvaguardas:
- Confirmas cada cambio. Los clientes que admiten la elicitación de
MCP te preguntan directamente. Con otros clientes, la primera llamada
solo devuelve una vista previa y un token de un solo uso. El asistente
debe mostrarte la vista previa y obtener tu acuerdo antes de llamar de
nuevo. Nada se envía a Netatmo antes de eso. Este segundo flujo depende
de que el asistente siga sus instrucciones; establece
NETATMO_MCP_CONFIRM=elicitationpara permitir cambios solo a través de un aviso de confirmación mostrado por tu cliente. Si tu cliente cancela cada cambio sin mostrar nada, estableceNETATMO_MCP_CONFIRM=token. - Límites. Las temperaturas deben mantenerse entre 7 y 28 °C. Las
consignas manuales terminan después de 3 h por defecto y 24 h como
máximo. Cambia estos con
NETATMO_MCP_MIN_TEMP,NETATMO_MCP_MAX_TEMPyNETATMO_MCP_MAX_SETPOINT_HOURS. - Interruptor de seguridad.
NETATMO_MCP_WRITE=0fuerza el modo de solo lectura, incluso con un inicio de sesión habilitado para escritura. - Registro de auditoría. Cada cambio aplicado o fallido se añade a
changes.logen tu carpeta de configuración. - Sin reintentos automáticos. Una escritura fallida nunca se reenvía a ciegas. Netatmo no tiene una API para eliminar un horario: los horarios creados aquí solo se pueden eliminar en la aplicación de Netatmo. Renombrar un horario y elegir un horario con el modo hogar "horario" utilizan parámetros de Netatmo no documentados, por lo que están marcados como experimentales. Detalles: docs/configuration.md.
Web y móvil (servidor remoto)
El servidor local es la opción más simple y privada. Para usar tu calefacción desde ChatGPT o Claude en la web y en tu teléfono, despliega las mismas herramientas como un servidor remoto en tu propia cuenta de Cloudflare (plan gratuito): remote/README.md.
- Mismas herramientas y salvaguardas. Solo lectura por defecto; modo escritura con vistas previas, confirmaciones y los mismos límites.
- Tus secretos permanecen en tu cuenta. Tus credenciales y tokens de la aplicación Netatmo están cifrados en reposo en tu cuenta de Cloudflare.
- Los asistentes inician sesión con OAuth. Apruebas cada uno en una página de consentimiento con tu contraseña de propietario, y puedes revocarlo.
- Un comando para vincular tu hogar:
npx netatmo-energy-mcp remote setup <your-worker-url>. - Opcional: permite que familiares o amigos conecten su propia cuenta de Netatmo con un código de invitación (
ONBOARDING=invite). Cada cuenta solo ve su propio hogar.
El flujo de inicio de sesión fue validado con ChatGPT (escritorio y móvil) y Claude (web, escritorio y móvil). Diseño: ADR-0013, ADR-0014.
Dispositivos compatibles
| Dispositivo | Tipo Netatmo | Estado |
|---|---|---|
| Termostato inteligente | NATherm1 | Probado. API validada en una instalación en vivo (2026-10-08) |
| Válvula de radiador inteligente | NRV | Probado. Misma instalación (6 válvulas) |
| Relé del termostato | NAPlug | Probado. Misma instalación |
| Termostato modulante OpenTherm / Gateway | OTM / OTH | Se espera que funcione, sin probar |
| BTicino Smarther con Netatmo | BNS | No compatible en v0.1 (probablemente necesita el alcance read_smarther) |
Ejecuta netatmo-energy-mcp probe y abre un
informe de compatibilidad de dispositivos
para ayudar a ampliar esta tabla. La salida de la sonda está saneada.
Asistentes de IA y clientes MCP compatibles
Este es un servidor MCP local (stdio) estándar, por lo que no está vinculado a un proveedor de IA. Cualquier cliente MCP que pueda iniciar servidores locales puede usarlo, con cualquier modelo que ejecute ese cliente.
| 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 y otros modelos de Copilot |
| Cursor, Windsurf / Devin Desktop, Zed, Warp, Kiro, JetBrains AI Assistant | múltiples modelos alojados |
| Cline, Roo Code, Kilo Code, Continue | múltiples, incluidos modelos locales (Ollama, LM Studio) |
| LM Studio | modelos abiertos locales: Llama, Qwen, Mistral, DeepSeek, … |
| Goose, AnythingLLM, LibreChat, Msty Studio | muchos proveedores, incluido Ollama |
| Open WebUI | Ollama y otros, a través del proxy mcpo |
Configuración para cada cliente, verificada contra la documentación oficial: examples/.
Asistentes web y móviles (aplicaciones y conectores de ChatGPT, Claude.ai y las aplicaciones móviles de Claude y ChatGPT) solo aceptan servidores MCP remotos. Usa el servidor remoto para ellos. Mistral Le Chat no ha sido probado.
Pruebas. El servidor se prueba con el cliente oficial del SDK de MCP y el MCP Inspector. La calidad de la llamada a herramientas con modelos locales pequeños varía según el modelo. Por favor, informa cualquier problema específico del cliente.
Autenticación
Este proyecto utiliza el flujo de código de autorización OAuth2 de Netatmo. Inicias sesión en netatmo.com; tu contraseña de Netatmo nunca es vista por esta herramienta.
Alcance. Por defecto solo se solicita read_thermostat, por lo que un token filtrado no podría cambiar tu calefacción. login --write también solicita write_thermostat.
Tu propia aplicación. Cada usuario registra una aplicación de desarrollador gratuita de Netatmo. El secreto del cliente no puede enviarse en código de código abierto.
Actualización. Los tokens de acceso se actualizan automáticamente. Varios clientes MCP ejecutándose a la vez se coordinan a través de un archivo de bloqueo, para que no invaliden los tokens de los demás.
Detalles: docs/authentication.md.
Privacidad y seguridad
Lo que sale de tu máquina. Solo solicitudes HTTPS a api.netatmo.com.
En modo de solo lectura solo llegan a 4 endpoints de lectura: el cliente rechaza cualquier escritura antes de tocar la red, y las pruebas lo garantizan. En modo escritura, un cambio se envía solo después de que lo confirmes.
Lo que permanece local.
- Las credenciales viven en
credentials.jsonen tu carpeta de configuración de usuario, legibles solo por tu cuenta (0600en macOS/Linux; una ACL restringida en Windows). - Sin telemetría, sin análisis y sin servicios de terceros.
- El servidor habla con tu cliente MCP a través de stdio y no abre ningún puerto de red.
Tu proveedor de IA. Los datos que devuelven las herramientas son leídos por el asistente que usas, por lo que son procesados por ese proveedor de modelos.
Sin datos de cuenta ni ubicación. Tu correo electrónico y las coordenadas de tu hogar nunca se devuelven.
Lee más:
Arquitectura
El cliente de Netatmo y los análisis son independientes de MCP. Las decisiones de diseño se registran como ADRs, y docs/architecture.md describe las capas.
Limitaciones
Estas provienen de la API de Netatmo Energy; los detalles están en docs/api-capabilities.md.
- Sin consumo de energía o gas. La actividad de la caldera es tiempo de demanda de calor. Con datos agregados, el número de ciclos del quemador no se puede conocer.
- Sin historial de demanda de calor de la válvula. Solo está disponible como valor actual. Un futuro recolector opcional podría registrarlo (ADR-0011).
- Sin temperatura exterior en la API de Energy. El contexto meteorológico está planificado para v0.4.
- La resolución del historial es de 30 minutos como máximo. Cada solicitud devuelve como máximo 1024 valores, por lo que los rangos largos usan escalas más gruesas.
- La documentación no coincide con la API en algunos lugares. Los datos en vivo muestran que las medidas de la caldera están en segundos, no en los minutos documentados. Este proyecto las convierte.
- Límites de velocidad. Netatmo limita las solicitudes por usuario y por aplicación. El servidor se autolimita y almacena en caché la topología y el estado actual.
Hoja de ruta
| Versión | Enfoque |
|---|---|
| v0.1 | Servidor MCP de solo lectura |
| v0.2 | Horarios, control de calefacción opcional |
| v0.3 | Servidor remoto para web y móvil (actual) |
| v0.3.x | Diagnósticos más ricos |
| v0.4 | Contexto meteorológico (Open-Meteo) |
| v0.5–v0.7 | Modelado térmico, predicciones, gemelo digital |
| v1.0 | Una interfaz estable |
El modo escritura nunca estará habilitado por defecto. Ver docs/roadmap.md.
Contribuciones
Los informes de errores, los informes de compatibilidad de dispositivos y las solicitudes de extracción son bienvenidos. Ver CONTRIBUTING.md para configurar el proyecto, que se ejecuta con respuestas de API simuladas: no se necesita cuenta de Netatmo. Por favor, sigue el Código de Conducta.
Licencia
Aviso legal
Este es un proyecto independiente de código abierto. No está afiliado con, respaldado por o patrocinado por Netatmo o Legrand. "Netatmo" es una marca comercial de su propietario y se usa aquí solo para describir compatibilidad. Úsalo bajo tu propio riesgo; la seguridad de la calefacción nunca debe depender de un asistente de IA.