Home Assistant: Guía Completa para Integrar tu IA con Claude

Home Assistant MCP te permite conectar un asistente de IA como Claude directamente a tu hogar inteligente, otorgándole la capacidad de leer tu configuración, escribir automatizaciones, gestionar dispositivos, editar paneles y solucionar problemas utilizando lenguaje natural. Esta guía abarca todo lo necesario para ponerlo en funcionamiento, desde comprender qué es realmente hasta conectar Claude Desktop y ponerlo a trabajar.

¿Qué es el Servidor MCP de Home Assistant?

MCP significa Model Context Protocol (Protocolo de Contexto de Modelo), un estándar abierto que define cómo las aplicaciones de IA se comunican con herramientas y fuentes de datos externas. En términos sencillos, es un puente que permite a un asistente de IA acceder e interactuar directamente con otro sistema, en lugar de solo responder a indicaciones de texto.

Existen tres implementaciones distintas de MCP en el ecosistema de Home Assistant, y es fácil confundirlas. Las dos primeras son integraciones oficiales del equipo principal de Home Assistant, llamadas Model Context Protocol y Model Context Protocol Server. La tercera es una aplicación desarrollada por la comunidad llamada The Unofficial and Awesome Home Assistant MCP Server o ha-mcp, una alternativa que va significativamente más allá en lo que permite a una IA hacer. Vale la pena entender qué las diferencia antes de instalar algo.

Integraciones Oficiales MCP de Home Assistant

El equipo principal de Home Assistant incluye dos integraciones MCP separadas que funcionan en direcciones opuestas.

1. La integración MCP Server hace que Home Assistant actúe como un servidor. Expone tu hogar inteligente hacia afuera a través de la API de Asistencia para que un cliente de IA externo como Claude Desktop pueda conectarse a él, consultar estados de dispositivos y controlar entidades. Tú decides qué entidades son visibles para la IA utilizando los mismos ajustes de exposición que se usan para el asistente de voz. Es una configuración limpia y sin florituras que no requiere software adicional y funciona bien para el control de dispositivos.
2. La integración MCP Client funciona en la dirección opuesta. En lugar de una IA externa accediendo a Home Assistant, esta integración permite que el agente de conversación que se ejecuta dentro de Home Assistant acceda a un servidor MCP externo y utilice sus herramientas. Un servidor de memoria, una herramienta de búsqueda web, un servicio de calendario: cualquier servidor MCP al que apunte se vuelve disponible para tu agente de conversación dentro de Home Assistant. No es para controlar Home Assistant desde afuera. Es para hacer que tu IA dentro de Home Assistant sea más inteligente dándole acceso a capacidades externas.

Ambas son integraciones estándar que se instalan a través de Ajustes > Dispositivos y Servicios. Ninguna requiere un complemento ni trabajo en línea de comandos. La limitación que comparten es que ambas pasan por la API de Asistencia, lo que significa que ninguna le da a una IA acceso a tu configuración, editor de automatizaciones, paneles o registro de entidades a nivel estructural.

The Unofficial and Awesome Home Assistant MCP Server o ha-mcp es arquitectónicamente diferente de las integraciones oficiales. En lugar de pasar por la API de Asistencia, se conecta a Home Assistant directamente a través de la API REST y la API WebSocket. Ese acceso de bajo nivel es lo que hace posibles las operaciones estructurales. La IA no está limitada a lo que el asistente de voz puede ver. Puede leer y escribir configuración, crear y editar automatizaciones, gestionar paneles, trabajar con el registro de entidades, instalar integraciones de HACS y extraer datos de energía e historial.

Actualmente, proporciona más de 86 herramientas en 24 categorías y se instala como una aplicación de Home Assistant o como una aplicación independiente en tu ordenador. También incluye un sistema de habilidades de agente que carga las mejores prácticas de Home Assistant directamente en el contexto de la IA, de modo que las automatizaciones y configuraciones que produce siguen la sintaxis actual en lugar de patrones obsoletos.

Donde se vuelve interesante es que ha-mcp se puede usar de dos maneras. Puedes conectar un cliente de IA externo como Claude Desktop directamente a él, que es lo que cubre esta guía. O puedes ejecutarlo como un servidor y conectar Home Assistant a él usando la integración MCP Client, poniendo sus herramientas a disposición de tu agente de conversación dentro de Home Assistant. Ambos enfoques funcionan.

Ha-mcp soporta una amplia gama de clientes de IA, incluyendo Claude Desktop, Claude Code, ChatGPT, Gemini CLI, Cursor, VS Code, GitHub Copilot, Windsurf, Cline, JetBrains IDEs, Raycast y más. Claude Desktop es el punto de partida más sencillo y el que esta guía se enfoca, pero el asistente de configuración en homeassistant-ai.github.io/ha-mcp cubre la configuración para cada cliente soportado.

¿Qué Versión de MCP Deberías Usar?

1. Elige la integración MCP Server integrada si tu objetivo es el control conversacional de dispositivos. Pedirle a una IA que apague las luces, compruebe si una puerta está cerrada o te diga la temperatura actual en una habitación es exactamente para lo que está diseñada. Sin software adicional, sin complementos, solo instala la integración y conecta tu cliente de IA.
2. Elige el Servidor MCP de la comunidad si quieres que la IA trabaje en tu configuración de Home Assistant en lugar de simplemente interactuar con ella. Escribir automatizaciones, editar paneles, gestionar entidades, instalar integraciones de HACS y diagnosticar problemas de configuración requieren el acceso REST y WebSocket más profundo que solo ha-mcp proporciona. Ese es el caso de uso en torno al cual se basa esta guía.

¿Qué Puede Hacer la IA en Home Assistant con MCP?

Una vez que ha-mcp está conectado a Claude, la interacción cambia de dar órdenes a tener una sesión de trabajo. Tú describes lo que quieres, Claude revisa tus entidades y configuración actuales, y luego actúa sobre ello. Los resultados se aplican directamente a tu instancia de Home Assistant.

Gestión de Automatizaciones y Scripts Potenciada por IA

Aquí es donde ha-mcp se vuelve útil para la mayoría de las personas. En lugar de abrir el editor de automatizaciones y construir disparadores y acciones manualmente, describes el comportamiento que deseas y Claude lo escribe utilizando los ID de tus entidades reales.

Le pedí que creara una automatización activada por movimiento para mi pasillo que enciende la luz al 30% de brillo entre el atardecer y la medianoche, y la apaga después de dos minutos sin más movimiento detectado. Claude recuperó mis entidades existentes, confirmó los ID correctos del sensor y la luz, comprobó si ya existía una automatización similar y creó la automatización completa con los disparadores, condiciones y acciones adecuados. Todo el proceso tardó unos 40 segundos.

También puede editar automatizaciones existentes. Le dije que ajustara la misma automatización para aumentar el brillo al 60% los fines de semana, y recuperó la configuración existente, hizo el cambio y lo aplicó sin que yo tocara ningún archivo YAML.

Más allá de las automatizaciones, Claude puede trabajar con la pila completa de automatización:

• Obtener, crear, editar y eliminar automatizaciones utilizando los ID de tus entidades reales
• Obtener, crear, editar y eliminar scripts
• Listar blueprints instalados y recuperar su configuración completa, incluyendo entradas, disparadores y acciones
• Importar nuevos blueprints desde una URL directamente a tu instancia de Home Assistant
• Extraer trazas de automatización para revisar exactamente qué se ejecutó, qué lo activó y dónde falló

Control Directo de Dispositivos, Entidades y Áreas

Claude tiene acceso completo a tus registros de entidades y dispositivos. Puedes pedirle que controle dispositivos directamente, consulte sus estados actuales y realice cambios estructurales en cómo se organizan las entidades en tu configuración.

Lo utilicé para auditar todas las entidades de mi sala de estar después de agregar un nuevo dispositivo, y devolvió una lista limpia agrupada por dominio con los estados actuales incluidos. Detectar el sensor duplicado que había agregado accidentalmente tomó segundos en lugar del desplazamiento manual habitual a través del registro de entidades.

Lo que puede hacer en esta categoría:

• Llamar a cualquier servicio de Home Assistant en cualquier entidad o dispositivo, incluyendo control masivo en múltiples entidades a la vez
• Obtener, actualizar y eliminar dispositivos del registro de dispositivos
• Obtener, actualizar y eliminar entidades del registro de entidades, incluyendo la gestión de la exposición al asistente de voz por entidad
• Crear, actualizar y eliminar áreas y plantas
• Crear, actualizar y eliminar grupos y zonas
• Crear, actualizar y eliminar etiquetas y categorías para organizar entidades

Construcción y Modificación de Paneles a través de IA

Ha-mcp otorga a Claude acceso completo a tus paneles de Home Assistant. Puedes pedirle que agregue una tarjeta, reorganice secciones, cambie tipos de tarjetas, actualice iconos o construya una vista completamente nueva desde cero. Sigue los patrones modernos de paneles por defecto, utilizando diseños de secciones y tarjetas de mosaico en lugar de tarjetas de entidad heredadas.

Le pedí que creara un nuevo panel personalizado y agregara un sensor de temperatura en una tarjeta de gráfico en el nuevo panel. Lo hizo en menos de 10 segundos, sin alucinar ni crear algo que no le había pedido:

Lo que puede hacer en esta categoría:

• Obtener, crear, actualizar y eliminar paneles
• Listar, agregar, actualizar y eliminar recursos de paneles como archivos JavaScript de tarjetas personalizadas
• Listar, crear, actualizar y eliminar entidades de ayuda, incluyendo booleanos de entrada, selectores de entrada, contadores, temporizadores y otros tipos de ayuda
• Leer, escribir, listar y eliminar archivos en directorios permitidos, incluyendo www, themes y custom_templates (beta, requiere el componente ha_mcp_tools)

Explorar, Instalar y Gestionar Aplicaciones e Integraciones

Si tienes HACS instalado, Claude puede buscar repositorios disponibles, comprobar qué está instalado actualmente e instalar nuevas integraciones o temas en tu nombre. También puede gestionar tus integraciones nativas y complementos directamente.

Lo que puede hacer en esta categoría:

• Buscar repositorios de HACS por palabra clave y obtener información detallada del repositorio
• Agregar repositorios a HACS y descargar integraciones, temas o recursos frontend
• Obtener detalles de cualquier complemento instalado, incluyendo su estado, opciones, puertos y configuración de ingress
• Actualizar opciones de configuración de complementos y gestionar ajustes de complementos
• Obtener detalles de integraciones nativas instaladas y habilitarlas o deshabilitarlas

Monitorización del Hogar y Análisis de Datos

Ha-mcp otorga a Claude acceso de lectura a una amplia gama de fuentes de datos en tu instancia de Home Assistant. Esto lo hace realmente útil para comprender qué está sucediendo en tu hogar a lo largo del tiempo, no solo cuál es el estado actual de las cosas.

Lo que puede hacer en esta categoría:

• Extraer el historial de estados de cualquier entidad durante un rango de tiempo especificado
• Recuperar registros de Home Assistant filtrados por relevancia
• Obtener y actualizar preferencias del panel de energía
• Obtener, crear, actualizar y eliminar eventos del calendario en cualquier integración de calendario conectada
• Obtener, agregar, actualizar y eliminar elementos de listas de tareas
• Capturar una instantánea de cualquier entidad de cámara e incluirla en el contexto de la conversación
• Evaluar cualquier plantilla de Home Assistant y devolver el resultado

Auditar, Diagnosticar y Solucionar Problemas de tu Configuración

Uno de los usos más infravalorados es pedirle a Claude que audite tu configuración en busca de problemas. Puede revisar tus automatizaciones y señalar conflictos, redundancias, sintaxis obsoleta o problemas potenciales, y luego solucionarlos en la misma sesión.

En una instancia de prueba, desconecté a propósito el SLZB-Ultima que estaba utilizando como Router de Borde Thread. Luego le pregunté a Claude si podía revisar los registros y decirme por qué fallaba la integración SMLight. Inmediatamente identificó el problema y me dio formas de solucionarlo.

Lo que puede hacer en esta categoría:

• Búsqueda profunda en todas las automatizaciones, scripts y entidades por palabra clave o patrón
• Obtener una visión general completa del sistema de tu instancia de Home Assistant, incluyendo entidades, áreas y dispositivos
• Obtener el estado actual de cualquier entidad
• Buscar entidades por nombre, área, dominio o etiqueta
• Verificar la salud del sistema y obtener un informe de cualquier problema conocido
• Comprobar actualizaciones pendientes en Home Assistant, complementos y HACS
• Validar tu configuración antes de aplicar cambios
• Crear y restaurar copias de seguridad
• Recargar la configuración central y reiniciar Home Assistant
• Enviar un informe de errores con el contexto completo del sistema
• Editar de forma segura configuration.yaml y archivos de paquetes, incluyendo copia de seguridad y validación automáticas (beta, requiere el componente compañero ha_mcp_tools y ENABLE_YAML_CONFIG_EDITING=true)

Uso de las Habilidades de Agente de Home Assistant MCP

El Servidor MCP de Home Assistant de la Comunidad proporciona a una IA las herramientas para interactuar con Home Assistant, pero las herramientas por sí solas no garantizan buenos resultados. Sin conocimiento del dominio, los agentes de IA tienden a cometer errores predecibles: depender demasiado de plantillas Jinja2 donde las construcciones nativas funcionan mejor, elegir el tipo de ayuda incorrecto o estructurar automatizaciones de maneras difíciles de mantener.

Home Assistant Agent Skills llena ese vacío. La habilidad actual se llama home-assistant-best-practices y cubre construcciones nativas de HA sobre plantillas, selección correcta de ayuda, modos de automatización, patrones de botones Zigbee, configuración de paneles y flujos de trabajo de refactorización seguros.

Las habilidades están integradas directamente en el Servidor MCP de la Comunidad y se sirven como recursos MCP. Cualquier cliente que admita recursos MCP puede descubrirlos automáticamente. Si el tuyo no lo hace, usa ha_list_resources y ha_read_resource para cargarlos manualmente antes de comenzar una tarea.

Para agentes de codificación como Claude Code, Cursor y Gemini CLI, las habilidades también se pueden instalar como archivos locales persistentes:

npx skills add homeassistant-ai/skills

Las instrucciones completas de instalación para cada cliente se encuentran en el repositorio de habilidades.

Cómo Instalar el Servidor MCP de Home Assistant

Antes de comenzar, es útil entender que existen dos rutas de instalación distintas y que funcionan de manera diferente. Elige una y síguela. No las mezcles.

El método de línea de comandos ejecuta el Servidor MCP de Home Assistant (Comunidad) directamente en tu PC Mac o Windows como un proceso local. Claude Desktop se comunica directamente utilizando tu URL de Home Assistant y un token de acceso de larga duración. No se necesita instalación de aplicaciones, ni mcp-proxy.

El método de aplicación (anteriormente complemento) ejecuta el Servidor MCP de Home Assistant de la Comunidad dentro del propio Home Assistant. Claude Desktop luego se conecta a él a través de una URL local utilizando mcp-proxy como puente. No se necesita token, pero mcp-proxy es obligatorio.

Ambos métodos funcionan. El método de línea de comandos es el que la mayoría de la gente termina usando con Claude Desktop, ya que el instalador maneja todo automáticamente. El método de aplicación es mejor si deseas que ha-mcp se ejecute independientemente de tu computadora, o si deseas usar un cliente HTTP como ChatGPT o la web de Claude.ai.

Instalar MCP vía PowerShell en Windows

Este método ejecuta el Servidor MCP de Home Assistant (Comunidad) como un proceso local en tu PC. Claude Desktop se comunica directamente con él, sin necesidad de instalar aplicaciones ni mcp-proxy. Este es el método más fácil para empezar.

1. Crea una cuenta en claude.ai si aún no la tienes.
2. Descarga Claude Desktop, inicia sesión y asegúrate de que funciona correctamente.
3. Cierra Claude Desktop completamente desde la bandeja del sistema.
4. Abre Windows PowerShell y ejecuta el siguiente comando.
5. Instala las herramientas necesarias y configura Claude Desktop con un entorno de demostración:

irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex

5. La ubicación del archivo de configuración de Claude se imprimirá en PowerShell.
6. O ábrelo manualmente con un editor de texto o ejecuta este comando:

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

7. Si instalaste Claude Desktop desde la Microsoft Store, ejecuta esto en PowerShell para encontrar la ruta de configuración correcta:

$pkg = Get-AppxPackage -Name Claude -ErrorAction SilentlyContinue | Select-Object -First 1; if ($pkg) { "$env:LOCALAPPDATA\Packages\$($pkg.PackageFamilyName)\LocalCache\Roaming\Claude\claude_desktop_config.json" } else { "$env:APPDATA\Claude\claude_desktop_config.json" }

8. Abre Home Assistant, haz clic en tu nombre de usuario en la esquina inferior izquierda.
9. Ve a la pestaña Seguridad, desplázate hasta Tokens de Acceso de Larga Duración y haz clic en Crear Token.
10. Cópialo inmediatamente ya que solo se muestra una vez.
11. Reemplaza los valores de demostración con tu propia URL de Home Assistant y token:

{
  "mcpServers": {
    "Home Assistant": {
      "command": "uvx",
      "args": ["ha-mcp@latest"],
      "env": {
        "HOMEASSISTANT_URL": "http://homeassistant.local:8123",
        "HOMEASSISTANT_TOKEN": "your_long_lived_token"
      }
    }
  }
}

12. Reinicia Claude Desktop desde Archivo > Salir y vuelve a abrirlo.
13. Pregunta “¿Puedes ver mi Home Assistant?” y debería devolver tus propias entidades en lugar de la demostración.
14. Haz clic en Permitir siempre.
15. Listo.

Instalar MCP vía Terminal en macOS

Este método ejecuta el Servidor MCP de Home Assistant (Comunidad) como un proceso local en tu Mac. Claude Desktop se comunica directamente con él, sin necesidad de instalar aplicaciones ni mcp-proxy.

1. Crea una cuenta en claude.ai si aún no la tienes.
2. Descarga Claude Desktop desde claude.ai/download, inicia sesión y asegúrate de que funciona.
3. Cierra Claude Desktop completamente desde la barra de menú.
4. Abre Terminal y ejecuta el comando siguiente. Instala uv y configura Claude Desktop con un entorno de demostración:

curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh

5. Abre tu archivo de configuración de Claude Desktop ejecutando esto en Terminal:

open "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

6. Abre Home Assistant, haz clic en tu nombre de usuario en la esquina inferior izquierda.
7. Ve a la pestaña Seguridad, desplázate hasta Tokens de Acceso de Larga Duración y haz clic en Crear Token.
8. Cópialo inmediatamente ya que solo se muestra una vez.
9. Reemplaza los valores de demostración en el archivo de configuración con tu propia URL de Home Assistant y token:

{
  "mcpServers": {
    "Home Assistant": {
      "command": "uvx",
      "args": ["ha-mcp@latest"],
      "env": {
        "HOMEASSISTANT_URL": "http://homeassistant.local:8123",
        "HOMEASSISTANT_TOKEN": "your_long_lived_token"
      }
    }
  }
}

10. Reinicia Claude Desktop desde el menú Claude > Salir y vuelve a abrirlo.
11. Pregunta “¿Puedes ver mi Home Assistant?” y debería devolver tus propias entidades en lugar de la demostración.
12. Haz clic en Permitir siempre cuando se te solicite.
13. Listo.

Instalar MCP como una Aplicación de Home Assistant

La aplicación ejecuta el Servidor MCP de Home Assistant No Oficial y Asombroso dentro del propio Home Assistant. Este método requiere Home Assistant OS o Supervised. Las instalaciones de contenedor y core deben usar el método de línea de comandos anterior. La aplicación se autentica automáticamente a través del Supervisor, por lo que no se necesita token, pero Claude Desktop requiere mcp-proxy para conectarse a ella.

1. Abre Home Assistant y ve a Ajustes > Aplicaciones > Instalar aplicación.
2. Haz clic en el menú de tres puntos en la esquina superior derecha y selecciona Repositorios.
3. Agrega la siguiente URL del repositorio:

https://github.com/homeassistant-ai/ha-mcp

4. Busca “Home Assistant MCP Server” en la tienda de aplicaciones e instálalo.
5. Haz clic en Iniciar, luego abre la pestaña Registros.
6. Copia tu URL MCP única de los registros:

MCP Server URL (local): http://192.168.x.x:9583/private_xxxxxxxxxxxxxxxx

7. Instala mcp-proxy para que Claude Desktop pueda conectarse a la aplicación:

uv tool install mcp-proxy

8. Abre tu archivo de configuración de Claude Desktop.

#MacOS
open "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

#Windows
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

9. Agrega lo siguiente, reemplazando la URL con la de los registros de tu aplicación:

{
  "mcpServers": {
    "home-assistant": {
      "command": "mcp-proxy",
      "args": ["--transport", "streamablehttp", "http://192.168.x.x:9583/private_xxxxxxxxxxxxxxxx"]
    }
  }
}

10. Reinicia Claude Desktop.
11. Pregunta “¿Puedes ver mi Home Assistant?” y debería devolver tus propias entidades.
12. Haz clic en Permitir siempre cuando se te solicite.
13. Listo.

Acceso Remoto vía Nabu Casa

Si utilizas Nabu Casa y quieres conectarte desde fuera de tu red local, la aplicación Webhook Proxy enruta el tráfico MCP a través de tu conexión Nabu Casa existente sin necesidad de reenvío de puertos ni configuración de túnel. Esto funciona sobre la instalación de la aplicación anterior.

Yo mismo uso Nabu Casa y así es como lo tengo configurado:

1. Instala la aplicación Webhook Proxy desde el mismo repositorio que agregaste anteriormente.
2. Iníciala y reinicia Home Assistant cuando se te solicite.
3. Verifica los registros de la aplicación para obtener tu URL remota:

MCP Server URL (remote): https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx

4. Usa esta URL en lugar de la local en la configuración de Claude Desktop mcp-proxy.
5. Listo.

Para otros métodos de acceso remoto, incluyendo Cloudflare Tunnel y proxies inversos personalizados, el asistente de configuración en homeassistant-ai.github.io/ha-mcp/setup cubre cada opción.

Conectando Otros Clientes de IA a Home Assistant MCP

La guía anterior cubre Claude Desktop en detalle, ya que es el punto de partida más común. El Servidor MCP de Home Assistant de la Comunidad funciona con una amplia gama de otros clientes de IA también. Todos ellos se conectan utilizando el método de línea de comandos uvx o la URL de la aplicación, dependiendo de su tipo de conexión.

Los clientes que admiten stdio ejecutan el servidor como un proceso local en tu máquina utilizando el método uvx, de la misma manera que lo hace Claude Desktop. Los clientes que admiten HTTP se conectan de forma remota directamente a la URL de la aplicación sin necesidad de mcp-proxy.

La lista completa de clientes compatibles incluye:

• Claude Desktop (stdio)
• Claude Code (stdio y HTTP)
• Cursor (stdio y HTTP)
• VS Code (stdio y HTTP)
• GitHub Copilot Agents (stdio y HTTP)
• Windsurf (stdio y HTTP)
• Cline (stdio y HTTP)
• ChatGPT (HTTP)
• Claude.ai web (HTTP)
• Gemini CLI (stdio)
• JetBrains IDEs (stdio)
• Zed (stdio)
• Continue (stdio y HTTP)
• Raycast (stdio y HTTP)
• Codex (stdio y HTTP)
• Open WebUI (HTTP)
• Copilot CLI (stdio y HTTP)

Errores Comunes del Servidor MCP de Home Assistant y Soluciones

Estos errores se aplican específicamente al Servidor MCP de Home Assistant de la Comunidad.

“Failed to start MCP server” en Claude Desktop

El comando uvx no pudo iniciarse. Comprueba lo siguiente:

• Ejecuta uvx --version en Terminal o PowerShell para confirmar que uv está instalado.
• Si no se encuentra, ejecuta el instalador de nuevo o instala uv manualmente como se describe en la sección de instalación.
• Comprueba tu archivo de configuración en busca de errores de sintaxis JSON. Una comilla o corchete faltante causará esto de forma silenciosa.

“MCP server disconnected” en Claude Desktop

El servidor se inició pero no puede alcanzar Home Assistant. Comprueba lo siguiente:

• Confirma que tu HOMEASSISTANT_URL es correcta y que Home Assistant se está ejecutando.
• Si utilizas una dirección IP local, verifica que puedes acceder a ella en un navegador.
• En macOS Sequoia 15 o posterior, ve a Ajustes del Sistema > Privacidad y seguridad > Red local y confirma que Claude Desktop está permitido. Una entrada bloqueada falla silenciosamente y se ve idéntica a un error de URL.

Error 404 al usar la URL de la aplicación

La aplicación Servidor MCP de Home Assistant no se está ejecutando o no se ha iniciado completamente:

• Abre los registros de la aplicación en Home Assistant y confirma que se muestra como en ejecución.
• Si actualizaste la aplicación recientemente, reiníciala y espera a que los registros muestren la URL MCP antes de reintentar.

Error 401 Unauthorized

Tu token de acceso de larga duración es incorrecto o ha sido eliminado. Esto se aplica solo al método de línea de comandos:

• Genera un nuevo token en tu perfil de Home Assistant bajo Seguridad > Tokens de Acceso de Larga Duración.
• Actualiza tu archivo de configuración de Claude Desktop con el nuevo token y reinicia Claude Desktop.

uvx está usando una versión antigua de Python en macOS

El Servidor MCP de Home Assistant de la Comunidad requiere Python 3.13 o superior:

• Ejecuta brew install python@3.13 seguido de uvx --refresh ha-mcp@latest.
• Si uvx aún detecta una versión anterior, agrega "--python", "3.13" al array de args en tu archivo de configuración de Claude Desktop.

Reflexiones Finales

El Servidor MCP de Home Assistant de la Comunidad es una de las integraciones de IA más prácticas disponibles para Home Assistant en este momento. Funciona con tu configuración real en lugar de una versión aislada de la misma, lo que hace que los resultados sean inmediatamente útiles en lugar de teóricos.

Dicho esto, vale la pena ser claro sobre el riesgo. Esto no es un asistente de voz que enciende y apaga luces. Estás dando a una IA acceso de escritura directo a tus automatizaciones, paneles, registro de entidades y archivos de configuración. Una indicación vaga o mal formulada puede resultar en la eliminación de automatizaciones, la sobrescritura de paneles o cambios de configuración difíciles de revertir. Siempre haz una copia de seguridad antes de cualquier sesión en la que planees realizar cambios estructurales, y trata cada indicación de confirmación de Claude como algo que vale la pena leer en lugar de simplemente hacer clic.

Comienza con una visión general del sistema, prueba una automatización simple y avanza desde ahí. Cuanto más lo uses, mejor te volverás para darle indicaciones precisas, y ahí es donde reside el valor real.