Asistente de hogar MCP

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

# Clone the repository
git clone https://github.com/your-repo/homeassistant-mcp.git

# Install dependencies 
cd homeassistant-mcp
npm install

# Build the project
npm run build

Ejecución del servidor

# Start with standard I/O transport (for AI assistant integration)
npm start -- --stdio

# Start with HTTP transport (for API access)
npm start -- --http

# Start with both transports
npm start -- --stdio --http

Configuración

Configure el servidor utilizando variables de entorno o un archivo .env :

# Server configuration
PORT=3000
NODE_ENV=development

# Execution settings
EXECUTION_TIMEOUT=30000
STREAMING_ENABLED=true

# Transport settings
USE_STDIO_TRANSPORT=true
USE_HTTP_TRANSPORT=true

# Debug and logging
DEBUG_MODE=false
DEBUG_STDIO=false
DEBUG_HTTP=false
SILENT_STARTUP=false

# CORS settings
CORS_ORIGIN=*

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:

import { LightsControlTool } from "./tools/homeassistant/lights.tool.js";
import { ClimateControlTool } from "./tools/homeassistant/climate.tool.js";

// Register tools
server.registerTool(new LightsControlTool());
server.registerTool(new ClimateControlTool());

API

Cuando se ejecuta con transporte HTTP, el servidor proporciona una API JSON-RPC 2.0:

POST /api/mcp/jsonrpc - Ejecutar una herramienta
GET /api/mcp/stream : conéctese a la transmisión SSE para obtener actualizaciones en tiempo real
GET /api/mcp/info - Obtener información del servidor
GET /health - Punto final de comprobación de estado

Integración con modelos de IA

Integración de Claude

import { createClaudeToolDefinitions } from "./mcp/index.js";

// Generate Claude-compatible tool definitions
const claudeTools = createClaudeToolDefinitions([
  new LightsControlTool(),
  new ClimateControlTool()
]);

// Use with Claude API
const messages = [
  { role: "user", content: "Turn on the lights in the living room" }
];

const response = await claude.messages.create({
  model: "claude-3-opus-20240229",
  messages,
  tools: claudeTools
});

Integración del cursor

Para utilizar el servidor MCP de Home Assistant con Cursor, agregue lo siguiente a su archivo .cursor/config/config.json :

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bash",
      "args": ["-c", "cd ${workspaceRoot} && bun run dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"],
      "env": {
        "NODE_ENV": "development",
        "USE_STDIO_TRANSPORT": "true",
        "DEBUG_STDIO": "true"
      }
    }
  }
}

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.txt
Luego 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 build
Habilite 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:

git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp

Configurar el entorno:

# Make my setup script executable
chmod +x scripts/setup-env.sh

# Run setup (defaults to development)
./scripts/setup-env.sh

# Or specify an environment:
NODE_ENV=production ./scripts/setup-env.sh

# Force override existing files:
./scripts/setup-env.sh --force

Configura tus ajustes:

Edite el archivo .env con los detalles de su Home Assistant
Obligatorio: agregue su HASS_TOKEN (token de acceso de larga duración)

Construir y lanzar con Docker:

# Standard build
./docker-build.sh

# Launch:
docker compose up -d

Opciones de compilación de Docker 🐳

Mi script de compilación de Docker ( docker-build.sh ) admite diferentes configuraciones:

1. Construcción estándar

./docker-build.sh

Funcionalidad básica del servidor MCP
Compatibilidad con API REST y WebSocket
Sin funciones de habla

2. Compilación habilitada para voz

./docker-build.sh --speech

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

./docker-build.sh --speech --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 💻

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Run with hot reload
bun --hot run dev

# Build for production
bun build ./src/index.ts --target=bun

# Run production build
bun run start

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 :

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bash",
      "args": ["-c", "cd ${workspaceRoot} && bun run dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"],
      "env": {
        "NODE_ENV": "development",
        "USE_STDIO_TRANSPORT": "true",
        "DEBUG_STDIO": "true"
      }
    }
  }
}

Escritorio de Claude 💬

Añade a tu configuración de Claude:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bun",
      "args": ["run", "start", "--port", "8080"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

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 :

ENABLE_SPEECH_FEATURES=true
ENABLE_WAKE_WORD=true
ENABLE_SPEECH_TO_TEXT=true
WHISPER_MODEL_PATH=/models
WHISPER_MODEL_TYPE=base

Elige tu motor STT:

# For standard Whisper
STT_ENGINE=whisper

# For Fast Whisper (GPU recommended)
STT_ENGINE=fast-whisper
CUDA_VISIBLE_DEVICES=0  # Set GPU device

Modelos disponibles 🤖

Elige según tus necesidades:

tiny.en : Precisión básica más rápida
base.en : Buen equilibrio (recomendado)
small.en : Mayor precisión, más lento
medium.en : Alta precisión, uso intensivo de recursos
large-v2 : Máxima precisión, gran consumo de recursos

Lanzamiento con funciones de voz

# Build with speech support
./docker-build.sh --speech

# Launch with speech features:
docker compose -f docker-compose.yml -f docker-compose.speech.yml up -d

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:

# Basic usage
npx homeassistant-mcp

# Or with environment variables
HASS_URL=http://your-ha-instance:8123 HASS_TOKEN=your_token npx homeassistant-mcp

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=true
Ejecute el servidor utilizando el script stdio-start:
./stdio-start.sh
Opciones 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

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tool-name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

Formato de respuesta

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    // Tool-specific result data
  }
}

Formato de respuesta de error

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32000,
    "message": "Error message",
    "data": {} // Optional error details
  }
}

Formato de notificación (del servidor al cliente)

{
  "jsonrpc": "2.0",
  "method": "notification-type",
  "params": {
    // Notification data
  }
}

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.json
Agregue 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:

# Start the server in stdio mode
npx homeassistant-mcp

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:

npx homeassistant-mcp 2>/dev/null

Instalación manual

Si prefiere instalar el paquete globalmente o localmente:

# Install globally
npm install -g homeassistant-mcp

# Then run
homeassistant-mcp

O instalar localmente:

# Install locally
npm install homeassistant-mcp

# Then run using npx
npx homeassistant-mcp

Integrations

Protocolo de contexto del modelo de asistente doméstico (MCP)

Descripción general

Características

Empezando

Prerrequisitos

Instalación

Ejecución del servidor

Configuración

Arquitectura

Herramientas

API

Integración con modelos de IA

Integración de Claude

Integración del cursor

Solución de problemas de integración del cursor

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 🐳

1. Construcción estándar

2. Compilación habilitada para voz

3. Compilación acelerada por GPU

Características de compilación

Configuración del entorno 🔧

Estructura de archivos 📁

Prioridad de carga ⚡

Desarrollo 💻

Comparación de rendimiento 📊

Documentación 📚

Documentación básica

Funciones avanzadas

Integración de clientes 🔗

Integración del cursor 🖱️

Escritorio de Claude 💬

Línea de comandos 💻

Características adicionales

Características del habla 🎤

Configuración de funciones de voz

Prerrequisitos

Configuración

Modelos disponibles 🤖

Lanzamiento con funciones de voz

Herramientas adicionales 🛠️

Licencia 📄

Autor 👨‍💻

Ejecutando con transporte de E/S estándar 📝

Características de MCP Stdio

Opción 1: Usar NPX (la más fácil)

Integración con Claude Desktop

Opción 2: Instalación local

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

Integración con Claude Desktop

Formato de mensaje JSON-RPC 2.0

Uso

Usando NPX (el más fácil)

Instalación manual

Uso avanzado

Appeared in Searches