Home Assistant con IA en tu Raspberry Pi: conecta Claude, ChatGPT y Gemini vía MCP paso a paso

Imagina que le pides a Claude en tu celular: "arma un sensor que muestre cuánta lluvia cayó hoy" y a los pocos segundos aparece funcionando en tu tablero de Home Assistant. Ese salto es lo que abrió el Model Context Protocol (MCP): la IA deja de recomendarte YAML y pasa a crear, leer y arreglar entidades, automatizaciones y dashboards por su cuenta.

En este tutorial vas a levantar toda la cadena sobre un Raspberry Pi: instalar Home Assistant OS desde cero, montar el servidor MCP de la comunidad (ha-mcp), abrirlo con seguridad hacia Claude, ChatGPT o Gemini, y. el ángulo que casi ningún tutorial cubre. dejarlo listo para controlar sensores GPIO y relés reales conectados al Pi. Al terminar tendrás una domótica que entiende lenguaje natural y una lista concreta de qué componentes conseguir en Chile.

Qué vas a aprender

• Preparar un Raspberry Pi 5 (o 4) desde cero con Home Assistant OS.
• Diferenciar el MCP oficial (limitado) del ha-mcp de comunidad (potente).
• Instalar el add on, conseguir tu URL privada y abrirla al mundo sin exponerte.
• Conectar Claude, ChatGPT y Gemini CLI con sus particularidades reales.
• Mantener el acceso seguro incluso si ya usas Cloudflare Access con mTLS.
• Sumar sensores GPIO y relés al Pi para que la IA los orqueste.

El concepto: qué es el MCP en Home Assistant y por qué te conviene

El Model Context Protocol es un puente estandarizado entre una IA y una aplicación. En Home Assistant se traduce en un servidor que expone tus entidades, servicios, historial, trazas y editor de YAML como herramientas ("tools") que Claude, ChatGPT o Gemini pueden invocar.

Existen dos implementaciones y elegirlas mal es la principal fuente de frustración:

Si solo buscas un asistente de voz mejorado ("prende la luz del living"), el oficial alcanza. Si quieres que la IA construya, la única opción real es ha-mcp, y es la que vamos a instalar acá.

Hardware: qué necesitas y por qué

Este tutorial se enfoca en el Raspberry Pi porque es la plataforma más económica y estable para correr Home Assistant OS 24/7. Los componentes base son:

• Raspberry Pi 5 (4 GB u 8 GB) o Raspberry Pi 4 (4 GB u 8 GB): el Pi 5 arranca más rápido y responde mejor con muchas integraciones; el Pi 4 sigue siendo suficiente para la mayoría de los hogares.
• Tarjeta microSD de 64 GB o más, clase A2: HAOS + snapshots + logs crece rápido. Menos de 32 GB se llena a los pocos meses.
• Fuente oficial Raspberry Pi (5 V/5 A para el Pi 5, 5 V/3 A para el Pi 4): fuentes genéricas provocan reinicios silenciosos y corrupción de la microSD.
• Cable de red Ethernet: WiFi funciona, pero en un servidor domótico el cable evita cortes.
• Gabinete con disipación pasiva o ventilador: el Pi 5 sube de temperatura bajo carga sostenida.
• Opcional pero muy recomendado: un módulo de relés 4 canales 5 V y un sensor DHT22 para tener algo físico que la IA pueda controlar desde el primer día.

Software y prerequisitos

Antes de tocar código:

• Home Assistant OS o Supervised corriendo en el Pi. Las apps/add ons solo existen en versiones con Supervisor: HA Core o Container puros no sirven.
• Acceso al App Store (Ajustes → Apps; en versiones anteriores a 2026.2 aparece como Ajustes → Add ons → Tienda de Add ons).
• Una vía de acceso remoto si vas a usar Claude o ChatGPT en la nube: Nabu Casa, un reverse proxy propio o un túnel de Cloudflare.
• Al menos una cuenta: Claude (gratis con un connector), ChatGPT (Plus como mínimo) o Google Gemini.

Si todavía no tienes acceso remoto configurado, un Cloudflare Tunnel sobre el Pi es la ruta más limpia y no requiere abrir puertos en tu router.

Paso 1: instala Home Assistant OS en el Raspberry Pi

Este paso lo sumamos nosotros porque el tutorial original asume HA ya andando. Si tu Pi ya tiene HAOS al día, saltea directo al Paso 2.

1. Descarga la imagen haos_rpi5-64-<versión>.img.xz (o haos_rpi4-64-... para el Pi 4) desde el sitio oficial de Home Assistant.
2. Usa el Raspberry Pi Imager (Windows, macOS o Linux) y elige "Use custom image" → selecciona el archivo .xz.
3. Graba la imagen en la microSD de 64 GB. No hace falta descomprimir manualmente.
4. Insértala en el Pi, conecta el cable Ethernet y por último la fuente (siempre en ese orden para no partir sin red).
5. En cualquier PC de la misma red entra a http://homeassistant.local:8123 y sigue el asistente inicial (nombre de casa, ubicación y usuario admin).

Ten en cuenta que la primera vez el Pi baja el sistema completo desde internet: puede tardar 15 a 20 minutos hasta que veas la pantalla de bienvenida. No apagues el Pi durante ese proceso o vas a corromper la instalación.

Paso 2: instala el add on MCP en Home Assistant

Con HAOS listo, agrega el repositorio del proyecto homeassistant-ai/ha-mcp (identificado oficialmente como The Unofficial and Awesome Home Assistant MCP Server):

1. Ve a Ajustes → Apps → App Store (o Add ons → Tienda de Add ons en versiones previas a 2026.2).
2. Toca los tres puntos arriba a la derecha → Repositorios y agrega la URL https://github.com/homeassistant-ai/ha-mcp.
3. Recarga la página, busca "Home Assistant MCP Server", instálalo y arráncalo.

Abre luego la pestaña Logs del add on: ahí aparece tu URL definitiva con un path aleatorio de 128 bits que ya funciona como autenticación:

🔐 MCP Server URL: http://<ha-ip>:9583/private_zctpwlX7ZkIAr7oqdfLPxw

No necesitas crear tokens ni usuarios extra: el add on se autentica solo contra el Supervisor y el path aleatorio ES el secreto. Guarda esa URL en un lugar seguro; la usarás en el Paso 4.

En el tab Configuration (o en "Open Web UI" del add on) recomiendo:

• Tool Search (enable_tool_search): déjalo apagado. Si usas Claude en modo Sonnet u Opus, el buscador propio de Claude ya cubre esa función y activar el de ha mcp genera choques. Solo enciéndelo con Claude Haiku u otros modelos sin búsqueda de herramientas propia.
• Tool Security Policies (enable_tool_security_policies): actívalo si quieres confirmación manual antes de que la IA toque cerraduras, alarma o escriba automatizaciones.
• Read Only Mode (read_only_mode): perfecto para la primera prueba o si compartes el HA con otras personas. Desactiva todas las herramientas que escriben.
• Backup Hint (backup_hint): déjalo en normal. Así la IA propone respaldos antes de cambios irreversibles.

Los tools individuales se pueden apagar o "pinnear" desde la web UI del add on. Aprovecha esa granularidad si hay funciones específicas que no quieres darle a la IA.

Con esto terminas el trabajo local. Desde tu red doméstica ya puedes apuntar cualquier cliente MCP (VS Code, Cursor, Claude Code) a esa URL y probar.

Paso 3: abre el servidor MCP hacia internet

Las IAs en la nube (Claude, ChatGPT) llaman al MCP desde sus servidores, no desde tu computador. Necesitas por lo tanto una URL pública con HTTPS. Hay dos rutas.

Opción A: Webhook Proxy (reutiliza tu acceso remoto actual)

Es la más simple si ya usas Nabu Casa o un reverse proxy. La app "Webhook Proxy for HA MCP" (del mismo repositorio) canaliza el tráfico MCP por tu acceso remoto ya existente, sin nombres de host adicionales:

1. Asegúrate de que el add on MCP del paso anterior esté corriendo.
2. Desde la misma tienda instala y arranca "Webhook Proxy for HA MCP".
3. Si NO usas Nabu Casa (tienes tu propio Cloudflare Tunnel, por ejemplo), abre la configuración de la app y escribe explícitamente tu URL pública de Home Assistant.
4. Reinicia Home Assistant desde Ajustes → Sistema → arriba a la derecha (reinicio completo, no solo el service).
5. Abre los Logs del Webhook Proxy y copia la URL remota que aparece:

MCP Server URL (remote): https://<your-external-url>/api/webhook/mcp_7eacf143b0f5d31269417ae3304ee534

El path /api/webhook/mcp_... se conserva entre reinicios porque el ID se guarda localmente.

Opción B: túnel Cloudflared dedicado (si arrancas sin acceso remoto)

Si aún no tienes acceso remoto, usa un túnel Cloudflared solo para el MCP. En la configuración del add on Cloudflared:

additional_hosts:
  - hostname: ha-mcp.tudominio.cl
    service: http://localhost:9583

Si localhost no resuelve desde el contenedor Cloudflared (típico cuando corren en containers distintos), reemplázalo por el hostname interno del contenedor del MCP (aparece en la página de info del add on, ej. b37de126-ha-mcp).

⚠️ Trampa clásica de Cloudflare: la opción "Block AI Training Bots" corta a los clientes de IA aunque el navegador entre sin problemas. Ve a Security → Bots y ponla en "do not block". Y si en el artículo del túnel Cloudflare restringiste el acceso a Chile, deja fuera de esa regla al hostname ha-mcp.*, o agrega el rango IP estable de Anthropic (160.79.104.0/21) como excepción. Claude y ChatGPT llaman desde EE.UU.

Paso 4: conecta Claude, ChatGPT o Gemini

La comparativa honesta antes de arremangarnos:

Claude. vía connector web (recomendado)

Es el flujo más limpio: se configura una vez y aparece en web + Desktop + móvil.

1. Ingresa a claude.ai → Personalizar → Connectors (o Customize).
2. Toca el "+" y agrega uno nuevo (ej. "Home Assistant").
3. Pega la URL remota del Paso 3 y guarda.
4. Para las tools de solo lectura puedes marcar "siempre permitir"; deja las de escritura/borrado con confirmación.

Si tu Cloudflare bloquea países, arma una regla Skip en la posición 1 para dejar pasar a Claude y ChatGPT:

((ip.src in {160.79.104.0/21}) or (ip.src in {2607:6bc0::/48})) and http.host eq "homeassistant.eure-domain.com"

Una vez conectado, verás las herramientas activas en Claude y puedes empezar a pedirle cosas como "muéstrame las automatizaciones que se dispararon hoy".

Claude Desktop. modo puramente local

Si prefieres que todo se quede en tu red y no usar el connector web, Claude Desktop habla MCP local por stdio, no por URL. El puente es mcp-proxy sobre uv:

winget install --id=astral-sh.uv -e

Cierra Claude Desktop (también el ícono en la bandeja) y edita claude_desktop_config.json (en Windows está en %APPDATA%\Claude). Como destino streamablehttp va la URL local del Paso 2:

{
  "mcpServers": {
    "home-assistant": {
      "command": "uvx",
      "args": ["mcp-proxy", "--transport", "streamablehttp", "http://homeassistant.local:9583/private_Odhrwersdgh234"]
    }
  }
}

Reinicia Claude Desktop una vez y la conexión queda operativa.

Claude Code. un solo comando

Dentro de tu sesión de Claude Code:

claude mcp add-json home-assistant '{
  "url": "eure-mcp-server-url",
  "type": "http"
}'

Reinicia Claude Code y quedas listo.

ChatGPT

1. En ChatGPT ve a Settings → Connectors → Advanced y activa Developer Mode (necesitas plan Plus o superior).
2. En Connectors toca Create e ingresa la URL remota del Paso 3.
3. ChatGPT te guía por un flujo OAuth 2.1 obligatorio.

Ese OAuth extra hace el setup un poco más pesado que Claude, pero también es una capa de seguridad más fuerte que la URL con secreto.

Gemini (solo CLI)

Actualmente la app y la web de Gemini no permiten conectar MCP: solo la Gemini CLI. En su settings.json:

{
  "mcpServers": {
    "home-assistant": {
      "url": "eure-mcp-server-url"
    }
  }
}

El path aleatorio en la URL cumple el rol de autenticación, así que no necesitas Bearer token.

Guía de mejores prácticas para la IA

Las versiones actuales de ha-mcp traen un tool interno llamado ha_get_skill_guide que se activa automáticamente cuando la IA lo necesita. Le explica cómo crear helpers, utility meters o sensores template como corresponde, así que ya no hace falta importar manualmente el paquete "Agent Skills" en Claude como pedían versiones anteriores. Revisa la doc del proyecto solo si tu cliente muestra un comportamiento raro.

Seguridad: convivir con Cloudflare Access + mTLS

Muchos escondemos Home Assistant detrás de Cloudflare Access con certificado de cliente (mTLS). Es una de las variantes más robustas... pero rompe los connectors de IA. Ni Claude ni ChatGPT pueden presentar tu certificado privado, y OpenAI lo aclara textualmente: sus custom connectors no envían mTLS ni API keys arbitrarias.

Si usas Webhook Proxy (Opción A)

El tráfico MCP entra por /api/webhook/... en el mismo hostname que tu HA. No hace falta un segundo hostname: basta con excluir ese path de la exigencia de mTLS. Si tu regla WAF viene del artículo del túnel Cloudflare, agrégale la excepción:

(http.host eq "homeassistant.tudominio.cl" and not cf.tls_client_auth.cert_verified and not starts_with(http.request.uri.path, "/api/webhook/"))

El path /api/webhook/ sigue seguro porque el ID aleatorio propio es la autenticación de ese endpoint. Tu UI de Home Assistant queda 100 % protegida con mTLS, y la IA entra por el mismo hostname sin necesidad de allowlist adicional.

Si usas hostname dedicado (Opción B)

Como no hay hostname común, no puedes descargar mTLS por path. La defensa se apoya en:

1. El path aleatorio del Paso 2 (secreto tipo password).
2. Restringir por IP al rango estable de Anthropic 160.79.104.0/21 para Claude.
3. Con ChatGPT es menos práctico allowlistear porque OpenAI cambia sus rangos seguido, pero el OAuth 2.1 obligatorio ya sube el piso de seguridad.

Mirando al futuro: túneles nativos

Tanto Anthropic (MCP Tunnels, en preview) como OpenAI (Secure MCP Tunnel, open source) están armando agentes que abren la conexión desde tu casa hacia la nube. Eso elimina la necesidad de exponer un puerto público, algo que a mediano plazo va a ser el estándar.

Opcional (y peligroso): editar YAML desde la IA

Algunas cosas de HA (como los REST template sensors) todavía requieren configuration.yaml a mano. Los tools ha_config_set_yaml y el acceso lector/escritor de archivos están marcados como Beta, requieren un componente companion y se activan desde "Advanced settings" en la Web UI del add on.

Regla de oro antes de habilitarlo: haz backup, después otro backup. Una IA que borre medio configuration.yaml puede dejar tu sistema sin arrancar. Actívalo solo si entiendes qué le estás abriendo y si ya tienes un ritmo regular de respaldos.

Variantes y mejoras

El tutorial original se queda en la conexión. Estas extensiones aprovechan el hardware físico del Pi y son las que llevan el proyecto al siguiente nivel:

• GPIO + relés controlados por la IA: conecta un módulo de 4 relés a los pines GPIO 17, 27, 22 y 23 del Pi. En Home Assistant configura la integración Raspberry Pi GPIO (vía HACS) o los relés MQTT via un ESP32. Después le puedes pedir a Claude: "crea una automatización que apague el relé del calefón entre 23:00 y 06:00" y la IA arma trigger, condition y action sola.
• Sensor DHT22 leído por IA: pega el DHT22 al Pi (VCC → 3.3 V, DATA → GPIO 4, GND → GND, resistencia pull up de 4.7 kΩ). Con la integración DHT expuesta como entity, la IA puede armar un dashboard de humedad/temperatura de tu pieza y sugerir automatizaciones basadas en los umbrales que le pases por texto.
• Cámara ESP32-CAM + notificaciones: enrola una ESP32-CAM en tu HA vía la integración ESPHome. Después le pides a la IA: "cuando el sensor de movimiento del living se dispare, saca foto con la cámara y mándamela por Telegram". La IA arma el alert y el notify desde cero.
• Control por voz local: si no quieres depender de la nube, corre Ollama o LM Studio en un PC de la LAN y conecta Claude Desktop con mcp-proxy local. todo el flujo se queda en tu red.

Personalización para Chile

En Chile puedes armar la base de este proyecto con componentes en MechatronicStore. Estos son los materiales típicos para el nodo central en el Pi (verifica precios y stock actualizados directamente en la tienda antes de comprar):

• Raspberry Pi 5 (4 GB u 8 GB). el corazón del servidor. Es la variante recomendada para HAOS: arranque más rápido, mejor manejo de add ons y sobra memoria para varios contenedores.
• Raspberry Pi 4 (4 GB u 8 GB). alternativa perfecta si el 5 se te va de presupuesto. Cumple sin problemas con Home Assistant, MCP y una decena de integraciones.
• Tarjeta MicroSD 64 GB clase A2. tamaño mínimo recomendado. Menos que eso llena en semanas por logs y snapshots.
• Fuente oficial Raspberry Pi 5 V / 5 A (Pi 5) o 5 V / 3 A (Pi 4). usar una fuente genérica es la principal causa de reinicios silenciosos y corrupción de la microSD.

Si buscas sumar el ángulo de "Variantes y mejoras" con hardware físico, MechatronicStore también trabaja módulos de relés 4 canales 5 V, sensores DHT22, ESP32-CAM y jumper hembra hembra 20 cm para conectar todo al header GPIO. Con eso el mismo Raspberry Pi pasa de correr HAOS a controlar cargas reales bajo lenguaje natural.

Troubleshooting rápido

• El cliente de IA no conecta por Cloudflare, pero el navegador sí: revisa primero la opción "Block AI Training Bots" (Security → Bots) y ponla en "do not block". También comprueba si tu WAF por país está bloqueando IPs de EE.UU.
• No aparece el menú "Apps" o "Add ons": solo existe con Home Assistant OS o Supervised (no en Container/Core puros). Desde 2026.2 el menú se llama "Apps".
• La IA reporta "Unknown tool": después de tocar Tool Search, Read Only Mode o habilitar/deshabilitar tools, el cliente cachea la lista vieja. Reiniciar el add on no alcanza: desconecta y reconecta el connector en la app (agrégalo de nuevo en ChatGPT, cierra Claude Desktop del todo, etc.).
• El connector no encuentra el MCP: con la Webhook Proxy App, comprueba que reiniciaste Home Assistant completo después de instalarla. Sin reinicio la ruta queda inactiva.
• ChatGPT no deja crear el connector: verifica que tengas Developer Mode activado y un plan Plus (o superior).
• Falla por mTLS: es lo esperado si tienes Cloudflare Access con certificado de cliente. Usa la Webhook Proxy con la excepción del path /api/webhook/ en la regla WAF, o migra a un hostname dedicado sin mTLS solo para el MCP.

Recursos

• Tutorial original (alemán): Home Assistant mit KI verbinden, MCP Server für Claude, ChatGPT & Gemini einrichten
• Repositorio GitHub del add on: homeassistant ai/ha mcp
• Home Assistant OS (imágenes oficiales): home assistant.io/installation
• Raspberry Pi Imager: raspberrypi.com/software
• Herramienta uv / uvx: astral.sh/uv

Versión chilena basada en el tutorial de raspberry.tips, extendida con guía de instalación de HAOS en Raspberry Pi 5 desde cero y componentes disponibles en MechatronicStore.