Protocolo de contexto del modelo de asistente doméstico (MCP)
Un protocolo estandarizado para que los asistentes de IA interactúen con Home Assistant, proporcionando una interfaz segura, tipificada y extensible para controlar dispositivos domésticos inteligentes.
Descripción general
El servidor del Protocolo de Contexto de Modelo (MCP) actúa como un puente entre los modelos de IA (como Claude, GPT, etc.) y Home Assistant, lo que permite a los asistentes de IA:
Ejecutar comandos en dispositivos Home Assistant
Recuperar información sobre la casa inteligente
Respuestas de transmisión para operaciones de larga duración
Validar parámetros y entradas
Proporcionar un manejo de errores consistente
Características
Arquitectura modular : separación clara entre transporte, middleware y herramientas
Interfaz tipificada : totalmente tipificada en TypeScript para una mejor experiencia del desarrollador
Transportes múltiples :
E/S estándar (stdin/stdout) para la integración de CLI
API HTTP/REST con soporte para eventos enviados por el servidor para transmisión
Sistema de middleware : validación, registro, tiempo de espera y manejo de errores
Herramientas integradas :
Control de luz (brillo, color, etc.)
Control de climatización (termostatos, HVAC)
Más por venir...
Sistema de complementos extensible : agregue fácilmente nuevas herramientas y capacidades
Respuestas de transmisión : soporte para operaciones de larga duración
Validación de parámetros : uso de esquemas Zod
Integración de Claude y Cursor : utilidades listas para usar para asistentes de IA
Empezando
Prerrequisitos
Node.js 16+
Instancia de Home Assistant (o puede usar las implementaciones simuladas para realizar pruebas)
Instalación
Ejecución del servidor
Configuración
Configure el servidor utilizando variables de entorno o un archivo .env
:
Arquitectura
El servidor MCP está construido con una arquitectura en capas:
Capa de transporte : maneja los protocolos de comunicación (stdio, HTTP)
Capa de middleware : procesa solicitudes a través de una canalización
Capa de herramientas : implementa una funcionalidad específica
Capa de recursos : administra recursos con estado
Herramientas
Las herramientas son la principal forma de añadir funcionalidad al servidor MCP. Cada herramienta:
Tiene un nombre único
Acepta parámetros tipificados
Devuelve resultados tipificados
Puede transmitir resultados parciales
Valida entradas y salidas
Ejemplo de registro de herramienta:
API
Cuando se ejecuta con transporte HTTP, el servidor proporciona una API JSON-RPC 2.0:
POST /api/mcp/jsonrpc
- Ejecutar una herramientaGET /api/mcp/stream
: conéctese a la transmisión SSE para obtener actualizaciones en tiempo realGET /api/mcp/info
- Obtener información del servidorGET /health
- Punto final de comprobación de estado
Integración con modelos de IA
Integración de Claude
Integración del cursor
Para utilizar el servidor MCP de Home Assistant con Cursor, agregue lo siguiente a su archivo .cursor/config/config.json
:
Esta configuración:
Ejecuta el servidor MCP con transporte stdio
Redirige toda la salida stderr a /dev/null
Utiliza grep para filtrar la salida estándar en busca de líneas que contengan
{"jsonrpc":"2.0"
, lo que garantiza una salida JSON-RPC limpia
Solución de problemas de integración del cursor
Si encuentra un error de "error al crear el cliente" al usar el servidor MCP con Cursor:
Asegúrese de estar utilizando el comando y los argumentos correctos en la configuración del cursor
El enfoque del script bash garantiza que solo los mensajes JSON-RPC válidos lleguen al cursor
Asegúrese de que el servidor esté construido ejecutando
bun run build
antes de intentar conectarse
Asegúrese de que el servidor esté enviando correctamente los mensajes JSON-RPC a stdout:
bun run dist/index.js --stdio 2>/dev/null | grep -E '\{"jsonrpc":"2\.0"' > json_only.txtLuego examine json_only.txt para verificar que solo contenga mensajes JSON-RPC válidos.
Asegúrese de que grep esté instalado en su sistema (debería estar disponible de forma predeterminada en la mayoría de los sistemas)
Intente reconstruir el servidor con:
bun run buildHabilite el modo de depuración configurando
DEBUG_STDIO=true
en las variables de entorno
Si el problema persiste, puedes intentar:
Reiniciando el cursor
Borrar la caché del cursor (Ayuda > Desarrollador > Borrar caché y recargar)
Usando un enfoque similar con Node.js:
{ "command": "bash", "args": ["-c", "cd ${workspaceRoot} && node dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"] }
Licencia
Instituto Tecnológico de Massachusetts (MIT)
Contribuyendo
¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.
Servidor MCP para Home Assistant 🏠🤖
Descripción general 🌐
El servidor MCP (Protocolo de Contexto de Modelo) es mi herramienta de integración ligera para Home Assistant, que proporciona una interfaz flexible para la gestión y automatización de dispositivos. Está diseñado para ser rápido, seguro y fácil de usar. Desarrollado con Bun para un rendimiento óptimo.
Características principales ✨
🔌 Control básico del dispositivo a través de API REST
📡 Eventos enviados por WebSocket/Servidor (SSE) para actualizaciones de estado
🤖 Gestión sencilla de reglas de automatización
Autenticación basada en JWT
🔄 Transporte de E/S estándar (stdio) para la integración con Claude y otros asistentes de IA
¿Por qué Bun? 🚀
Elegí Bun como tiempo de ejecución por varios beneficios clave:
⚡ Rendimiento increíblemente rápido
Hasta 4 veces más rápido que Node.js
Compatibilidad con TypeScript incorporada
Operaciones optimizadas del sistema de archivos
🎯 Solución todo en uno
Gestor de paquetes (más rápido que npm/yarn)
Bundler (no necesita paquete web)
Ejecutor de pruebas (pruebas integradas)
Transpilador de TypeScript
🔋 Funciones integradas
Controlador SQLite3
carga de archivos .env
Cliente/servidor WebSocket
Vigilante de archivos
Corredor de pruebas
💾 Eficiente en el uso de recursos
Menor uso de memoria
Arranques en frío más rápidos
Mejor utilización de la CPU
🔄 Compatibilidad con Node.js
Ejecuta la mayoría de los paquetes npm
Compatible con Express/Fastify
API nativas de Node.js
Prerrequisitos 📋
Tiempo de ejecución de Bun (v1.0.26+)
🏡 Instancia de Home Assistant
🐳 Docker (opcional, recomendado para la implementación)
🖥️ Node.js 18+ (opcional, para funciones de voz)
GPU NVIDIA con soporte CUDA (opcional, para un procesamiento de voz más rápido)
Inicio rápido 🚀
Clonar mi repositorio:
Configurar el entorno:
Configura tus ajustes:
Edite el archivo
.env
con los detalles de su Home AssistantObligatorio: agregue su
HASS_TOKEN
(token de acceso de larga duración)
Construir y lanzar con Docker:
Opciones de compilación de Docker 🐳
Mi script de compilación de Docker ( docker-build.sh
) admite diferentes configuraciones:
1. Construcción estándar
Funcionalidad básica del servidor MCP
Compatibilidad con API REST y WebSocket
Sin funciones de habla
2. Compilación habilitada para voz
Incluye detección de palabras de activación
Capacidades de conversión de voz a texto
Extrae las imágenes requeridas:
onerahmet/openai-whisper-asr-webservice
rhasspy/wyoming-openwakeword
3. Compilación acelerada por GPU
Todas las funciones del habla
Aceleración de GPU CUDA
Optimizado para un procesamiento más rápido
Tipo de cálculo Float16 para un mejor rendimiento
Características de compilación
🔄 Asignación automática de recursos
💾 Construcción consciente de la memoria
📊 Gestión de cuotas de CPU
🧹 Limpieza automática
📝 Registros de compilación detallados
📊 Resumen y estado de la compilación
Configuración del entorno 🔧
He implementado un sistema de configuración jerárquico:
Estructura de archivos 📁
.env.example
- Mi plantilla con todas las opciones.env
- Su configuración (copia de .env.example)Anulaciones de entorno:
.env.dev
- Configuración de desarrollo.env.prod
- Configuración de producción.env.test
- Configuración de pruebas
Prioridad de carga ⚡
Los archivos se cargan en este orden:
.env
(configuración base)Archivo específico del entorno:
NODE_ENV=development
→.env.dev
NODE_ENV=production
→.env.prod
NODE_ENV=test
→.env.test
Los archivos posteriores anulan los anteriores.
Desarrollo 💻
Comparación de rendimiento 📊
Operación | Bollo | Node.js |
Instalar dependencias | ~2 segundos | ~15 segundos |
Arranque en frío | 300 ms | 1000 ms |
Tiempo de construcción | 150 ms | 4000 ms |
Uso de la memoria | ~150 MB | ~400 MB |
Documentación 📚
Documentación básica
Funciones avanzadas
Procesamiento del lenguaje natural : análisis y control de automatización impulsados por IA
Guía de indicaciones personalizadas : crear y personalizar el comportamiento de la IA
Extras y herramientas : utilidades adicionales y funciones avanzadas
Integración de clientes 🔗
Integración del cursor 🖱️
Agregar a .cursor/config/config.json
:
Escritorio de Claude 💬
Añade a tu configuración de Claude:
Línea de comandos 💻
Los usuarios de Windows pueden utilizar el script proporcionado:
Ir al directorio
scripts
Ejecute
start_mcp.cmd
Características adicionales
Características del habla 🎤
El servidor MCP admite opcionalmente capacidades de procesamiento de voz:
Detección de palabras de activación ("hola jarvis", "ok google", "alexa")
🎯 Conversión de voz a texto mediante susurro rápido
🌍 Soporte para múltiples idiomas
🚀 Soporte de aceleración de GPU
Configuración de funciones de voz
Prerrequisitos
🐳 Docker instalado y funcionando
🎮 GPU NVIDIA con CUDA (opcional)
💾 4 GB+ de RAM (se recomiendan 8 GB+)
Configuración
Habilitar voz en
.env
:
Elige tu motor STT:
Modelos disponibles 🤖
Elige según tus necesidades:
tiny.en
: Precisión básica más rápidabase.en
: Buen equilibrio (recomendado)small.en
: Mayor precisión, más lentomedium.en
: Alta precisión, uso intensivo de recursoslarge-v2
: Máxima precisión, gran consumo de recursos
Lanzamiento con funciones de voz
Herramientas adicionales 🛠️
He incluido varias herramientas potentes en el directorio extra/
para mejorar su experiencia con Home Assistant:
CLI del analizador de Home Assistant (
ha-analyzer-cli.ts
)Análisis de automatización profunda mediante modelos de IA
Análisis de vulnerabilidades de seguridad
Sugerencias de optimización del rendimiento
Métricas de salud del sistema
Ejemplo de conversión de voz a texto (
speech-to-text-example.ts
)Detección de palabras de activación
Transcripción de voz a texto
Compatibilidad con varios idiomas
Compatibilidad con aceleración de GPU
Configuración del escritorio de Claude (
claude-desktop-macos-setup.sh
)Instalación automatizada de Claude Desktop para macOS
Configuración del entorno
Configuración de integración de MCP
Consulte la Documentación adicional para obtener instrucciones de uso detalladas y ejemplos.
Licencia 📄
Licencia MIT. Ver LICENCIA para más detalles.
Autor 👨💻
Creado por jango-blockchained
Ejecutando con transporte de E/S estándar 📝
El servidor MCP admite un modo de transporte estándar JSON-RPC 2.0 para la integración directa con asistentes de IA como Claude:
Características de MCP Stdio
✅ Compatibilidad con JSON-RPC 2.0 : Soporte completo para el estándar de protocolo MCP
✅ Compatibilidad con NPX : Ejecútelo directamente sin instalación usando npx homeassistant-mcp
✅ Configuración automática : crea los directorios necesarios y la configuración predeterminada
✅ Multiplataforma : funciona en macOS, Linux y Windows
✅ Integración con Claude Desktop : lista para usar con Claude Desktop
✅ Validación de parámetros : Validación automática de los parámetros de la herramienta
✅ Manejo de errores : Códigos de error estandarizados y manejo
✅ Registro detallado : registra en archivos sin contaminar stdio
Opción 1: Usar NPX (la más fácil)
Ejecute el servidor MCP directamente sin instalación usando npx:
Esto hará lo siguiente:
Instalar el paquete temporalmente
Ejecutar automáticamente en modo stdio con transporte JSON-RPC 2.0
Crear un directorio de registros para el registro
Crea un archivo .env predeterminado si no está presente
Perfecto para la integración con Claude Desktop u otros clientes MCP.
Integración con Claude Desktop
Para utilizar MCP con Claude Desktop:
Abrir la configuración de Claude Desktop
Vaya a la pestaña "Avanzado"
En "Servidor MCP", seleccione "Personalizado"
Ingrese el comando:
npx homeassistant-mcp
Haga clic en "Guardar"
Claude ahora utilizará el servidor MCP para la integración de Home Assistant, lo que le permitirá controlar su casa inteligente directamente a través de Claude.
Opción 2: Instalación local
Actualice su archivo
.env
para habilitar el transporte stdio:USE_STDIO_TRANSPORT=trueEjecute el servidor utilizando el script stdio-start:
./stdio-start.shOpciones disponibles:
./stdio-start.sh --debug # Enable debug mode ./stdio-start.sh --rebuild # Force rebuild ./stdio-start.sh --help # Show help
Cuando se ejecuta en modo stdio:
El servidor se comunica a través de stdin/stdout utilizando el formato JSON-RPC 2.0
No se ha iniciado ningún servidor HTTP
El registro de la consola está deshabilitado para evitar contaminar la transmisión stdio
Todos los registros se escriben en los archivos de registro en el directorio
logs/
Formato de mensaje JSON-RPC 2.0
Formato de solicitud
Formato de respuesta
Formato de respuesta de error
Formato de notificación (del servidor al cliente)
Códigos de error admitidos
Código | Descripción | Significado |
-32700 | Error de análisis | Se recibió un JSON no válido |
-32600 | Solicitud no válida | JSON no es un objeto de solicitud válido |
-32601 | Método no encontrado | El método no existe o no está disponible |
-32602 | Parámetros no válidos | Parámetros de método no válidos |
-32603 | Error interno | Error interno de JSON-RPC |
-32000 | Ejecución de herramientas | Error al ejecutar la herramienta |
-32001 | Error de validación | La validación de parámetros falló |
Integración con Claude Desktop
Para utilizar este servidor MCP con Claude Desktop:
Crea o edita tu configuración de Claude Desktop:
# On macOS nano ~/Library/Application\ Support/Claude/claude_desktop_config.json # On Linux nano ~/.config/Claude/claude_desktop_config.json # On Windows notepad %APPDATA%\Claude\claude_desktop_config.jsonAgregue la configuración del servidor MCP:
{ "mcpServers": { "homeassistant-mcp": { "command": "npx", "args": ["homeassistant-mcp"], "env": { "HASS_TOKEN": "your_home_assistant_token_here", "HASS_HOST": "http://your_home_assistant_host:8123" } } } }Reinicie Claude Desktop.
En Claude, ahora puedes utilizar las herramientas MCP de Home Assistant.
Formato de mensaje JSON-RPC 2.0
Uso
Usando NPX (el más fácil)
La forma más sencilla de utilizar el servidor MCP de Home Assistant es a través de NPX:
Esto automáticamente:
Iniciar el servidor en modo stdio
Salida de mensajes JSON-RPC a stdout
Enviar mensajes de registro a stderr
Crea un directorio de registros si no existe
Puede redirigir stderr para ocultar registros y solo ver la salida JSON-RPC:
Instalación manual
Si prefiere instalar el paquete globalmente o localmente:
O instalar localmente:
Uso avanzado
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Control de dispositivo inteligente 🎮 💡 Luces: Brillo, color, RGB 🌡️ Clima: Temperatura, HVAC, humedad 🚪 Cubiertas: Posición e inclinación 🔌 Interruptores: Encendido/apagado 🚨 Sensores: Monitoreo de estado
Organización Inteligente 🏠 Agrupación con conciencia del contexto.
Arquitectura Robusta 🛠️ Manejo de errores, validación de estados...
- Descripción general
- Características
- Empezando
- Arquitectura
- Integración con modelos de IA
- Licencia
- Contribuyendo
- Servidor MCP para Home Assistant 🏠🤖
- Descripción general 🌐
- Características principales ✨
- ¿Por qué Bun? 🚀
- Prerrequisitos 📋
- Inicio rápido 🚀
- Opciones de compilación de Docker 🐳
- Configuración del entorno 🔧
- Desarrollo 💻
- Documentación 📚
- Integración de clientes 🔗
- Características adicionales
- Licencia 📄
- Autor 👨💻
- Ejecutando con transporte de E/S estándar 📝
- Uso
Related MCP Servers
- -securityAlicense-qualityAccess Home Assistant data and control devices (lights, switches, thermostats, etc).Last updated -6431Apache 2.0
- -securityFlicense-qualityEnables users to control Google Home smart plugs using the Smart Home API with OAuth2 authentication, offering real-time device state management and control operations.
- AsecurityAlicenseAqualityEnables AI assistants to control SwitchBot devices, providing functionalities like device management, scene execution, and sensor information monitoring through the SwitchBot API.Last updated -3ISC License
- -securityAlicense-qualityEnables users to control Govee LED devices using the Govee API, with features for turning devices on/off, setting colors, and adjusting brightness through a CLI or MCP clients.Last updated -3MIT License
Appeared in Searches
- A server for finding information about smart technology and intelligence
- An MCP for managing lifestyle, coordinating daily routines, exercise, and study tasks
- Searching for information about license types or information starting with 'f'
- Finding MCP Servers Providing Insights for a Conversational Voice Interface
- A server for finding information about guitars