ha-mcp

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona a los asistentes de IA acceso a Home Assistant, permitiendo el control del hogar inteligente y la gestión de automatizaciones.

GitHub

Prueba este MCPPatrocinado

Documentación

ha-mcp

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona a los asistentes de IA acceso a Home Assistant, permitiendo el control del hogar inteligente y la gestión de automatizaciones.

Características

41 Herramientas Especializadas: Consultas de entidades, CRUD de automatizaciones, gestión de ayudantes, scripts, escenas, dispositivos, áreas, etiquetas, pisos, zonas, personas, etiquetas, trazas, planos, actualizaciones, tareas pendientes, calendarios, cámaras, paneles, registro del sistema y más
Arquitectura Híbrida: WebSocket para la mayoría de las operaciones, API REST para CRUD de automatizaciones/scripts/escenas
CRUD Completo: Crear, leer, actualizar, eliminar automatizaciones/scripts/escenas/ayudantes
Acceso Profundo al Sistema: Consultar registros, analizar dependencias, acceder al libro de registro, validar configuración
Salida Flexible: Lenguaje natural (optimizado para LLM) y formatos JSON
Control de Acceso: Modo de solo lectura, lista blanca/negra, control fino a nivel de acción
Reconexión Automática: Reconexión automática con retroceso exponencial
Confirmación Posterior a la Mutación: Sondeo automático de estado después de crear/actualizar/eliminar para confirmar cambios

vs. Otros Servidores MCP para Home Assistant

Existen dos alternativas: la integración oficial de HA MCP (componente central integrado, ~15 herramientas de intención) y la comunitaria homeassistant-ai/ha-mcp (Python/FastMCP, 88 herramientas).

Elija ha-mcp si necesita:

Gestión completa del ciclo de vida de automatizaciones, scripts, escenas y ayudantes (crear, editar, eliminar)
Parcheo JSON RFC 6902 y semántico para automatizaciones y paneles sin sobrescrituras de archivos completos
Gestión de ayudantes en 41 tipos, incluidos flujos de entrada de configuración de múltiples pasos y subtipos de plantillas
Diagnósticos profundos (análisis de radio de explosión, gráficos de dependencias, búsqueda de referencias entre configuraciones)
Diferenciación de estado posterior a la mutación (Smart Wait confirma entity: off -> on en línea)
Uso eficiente del contexto LLM: 42 herramientas consolidadas consumen ~3,500 tokens de espacio de esquema, en comparación con más de 15,000 tokens para 88 herramientas separadas
Un único binario estático con cero dependencias de tiempo de ejecución y bajo uso de memoria

Elija la integración oficial si necesita control básico de dispositivos con cero configuración externa, o depende estrictamente de la configuración de exposición de Assist Voice.

Elija la comunidad ha-mcp si necesita ejecución dentro de HA mediante HACS o Add-on, colas de políticas de aprobación con intervención humana, o filtros de ocultación de entidades.

Consulte docs/feature-comparison.md para una matriz de características detallada de tres vías.

Instalación

Desde Binario

Descargue la última versión desde la página de Lanzamientos.

# Linux/macOS
tar -xzf ha-mcp_linux_amd64.tar.gz
chmod +x ha-mcp
sudo mv ha-mcp /usr/local/bin/

# Windows: extract ha-mcp_windows_amd64.zip and add to PATH

Desde el Código Fuente

Requiere Go 1.27 o posterior.

git clone https://github.com/zorak1103/ha-mcp.git
cd ha-mcp
task install-hooks  # install git pre-commit hook (auto-fixes gofmt on every commit)
task lint:install   # install golangci-lint built with your local Go toolchain
go build -o ha-mcp ./cmd/ha-mcp

Paquetes Linux

Los paquetes RPM y DEB están disponibles en los lanzamientos:

sudo dpkg -i ha-mcp_amd64.deb   # Debian/Ubuntu
sudo rpm -i ha-mcp_amd64.rpm    # RHEL/Fedora

Docker

docker pull zorak1103/ha-mcp:latest
docker run -d --name ha-mcp -p 8080:8080 \
  -e HA_URL=http://homeassistant.local:8123 \
  zorak1103/ha-mcp:latest

Consulte docs/configuration.md para opciones de Docker, HTTPS/WSS, soporte de proxy y todas las variables de entorno.

Inicio Rápido

Obtenga un token de acceso de larga duración desde la página de perfil de su Home Assistant.
Inicie el servidor:

# With flags
ha-mcp --ha-url http://homeassistant.local:8123 --ha-token your-token

# Or initialize config files first
ha-mcp init   # creates config.yaml and .env
ha-mcp        # start with config file

Conecte su cliente de IA. Ejemplo para Claude Desktop:

{
  "mcpServers": {
    "homeassistant": {
      "type": "http",
      "url": "http://localhost:8080",
      "headers": { "Authorization": "Bearer your-ha-access-token" }
    }
  }
}

Consulte docs/configuration.md para configuraciones de Cline, opencode y otros clientes.

Comandos Disponibles

Comando	Descripción
`ha-mcp`	Iniciar el servidor MCP
`ha-mcp init`	Crear config.yaml y .env en el directorio actual
`ha-mcp config`	Mostrar la configuración efectiva (tokens enmascarados)
`ha-mcp --help`	Mostrar ayuda y banderas disponibles

Herramientas Disponibles

42 herramientas organizadas por dominio. Referencia completa en docs/tools.md.

Siete temas de guía también están disponibles como recursos MCP bajo URIs skill://ha-mcp/<slug> (selección de formato, patrones de automatización, resiliencia de plantillas, selección de ayudantes, seguridad de paneles, renombrado de entidades, flujo de trabajo de depuración).

Categoría	Cantidad	Destacados
Entidad	5	`query_entities` (historial/estadísticas/salud), `get_state`, `analyze_entity`
Registro	10	`get_registry`, `manage_area/label/floor/zone/person/tag/entity/device`
Automatización	1	`manage_automation` (CRUD, alternar, cobertura, parcheo JSON + semántico)
Ayudantes	2	`manage_helper` (41 tipos), `helper_action`
Scripts y Escenas	2	`manage_script`, `manage_scene` (CRUD + ejecutar/activar + parcheo JSON + semántico)
Análisis	4	`analyze_entity`, `get_entity_dependencies`, `analyze_target`, `find_references`
Servicios	2	`call_service`, `list_services` (llamadas de tipo de respuesta mediante `return_response`)
Historial/Libro de registro	2	`query_entities` modos, `get_logbook` (entradas + correlación)
Paneles/Medios	4	`manage_dashboard` (parcheo JSON + semántico), `browse_media`, `manage_camera`, `sign_media_path`
Calendarios y Tareas pendientes	2	`manage_calendar`, `manage_todo`
Sistema/Administración	7	`get_system_info`, `validate_config`, `manage_update`, `manage_blueprint`
Registros	1	`manage_system_log` (listar entradas WARN/ERROR, limpiar buffer circular)
Estadísticas	1	`manage_statistics` (listar, validar, limpiar estadísticas a largo plazo del registrador)
HACS	1	`manage_hacs` (listar, descargar, instalar, repositorios personalizados)
Guía	1	`get_skill` (acción=list para descubrir habilidades, acción=read para obtener contenido)

Control de Acceso

ha-mcp proporciona modo de solo lectura, lista blanca y filtrado de lista negra a nivel de herramienta y acción:

# config.yaml - read-only monitoring
server:
  read_only: true

# Or block specific operations
server:
  tool_filter:
    blacklist:
      - "call_service"
      - "manage_*:delete"

Consulte docs/access-control.md para patrones glob, filtrado por categoría (*:write) y escenarios de ejemplo.

Arquitectura

AI Client → HTTP/JSON-RPC → ha-mcp MCP Server
                                    │
               ┌────────────────────┴────────────────────┐
               │ WebSocket (primary)                      │ REST API
               │ - State queries, service calls           │ - Automation CRUD
               │ - Helper CRUD, Registry access           │ - Script/Scene CRUD
               └────────────────────┬────────────────────┘
                                    │
                             Home Assistant

Consulte docs/architecture.md para la estructura del proyecto, comandos de compilación y configuración de pruebas de integración.

Solución de Problemas

Consulte docs/troubleshooting.md para problemas de conexión WebSocket, modo de depuración y soluciones de errores comunes.

Desarrollo

Hay un contenedor de desarrollo preconfigurado disponible; consulte .devcontainer/README.md.

Requisitos previos: Go 1.27+, golangci-lint v2, Docker (opcional)

go build -o ha-mcp ./cmd/ha-mcp    # Build
go test ./...                       # Unit tests
golangci-lint run --timeout=5m ./...  # Lint

Si golangci-lint entra en pánico con "file requires newer Go version", su binario instalado localmente fue compilado con una cadena de herramientas Go más antigua que la de PATH. Ejecute task lint:install para recompilarlo contra su cadena de herramientas actual.

Consulte docs/architecture.md para la configuración de pruebas de integración y docs/integration-tests.md para la documentación completa del conjunto de pruebas.

Contribuciones

Consulte CONTRIBUTING.md para el flujo de trabajo completo (comandos de tareas, requisito de TDD, configuración de pruebas de integración, reglas del linter y la lista de verificación de documentación para nuevas herramientas). Lea también el Código de Conducta.

Licencia

Licencia GPL-3.0 - consulte LICENSE para más detalles.

Agradecimientos

Especificación del Protocolo de Contexto de Modelo
API WebSocket de Home Assistant
coder/websocket - Biblioteca WebSocket pura en Go