advanced-homeassistant-mcp

A standardized protocol for AI assistants to interact with Home Assistant, providing a secure, typed, and extensible interface for controlling smart home devices.

The Model Context Protocol (MCP) server acts as a bridge between AI models (like Claude, GPT, etc.) and Home Assistant, enabling AI assistants to:

• Execute commands on Home Assistant devices
• Retrieve information about the smart home
• Stream responses for long-running operations
• Validate parameters and inputs
• Provide consistent error handling

• Modular Architecture - Clean separation between transport, middleware, and tools
• Typed Interface - Fully TypeScript typed for better developer experience
• Multiple Transports:
  • Standard I/O (stdin/stdout) for CLI integration
  • HTTP/REST API with Server-Sent Events support for streaming
• Middleware System - Validation, logging, timeout, and error handling
• Built-in Tools:
  • Light control (brightness, color, etc.)
  • Climate control (thermostats, HVAC)
  • More to come...
• Extensible Plugin System - Easily add new tools and capabilities
• Streaming Responses - Support for long-running operations
• Parameter Validation - Using Zod schemas
• Claude & Cursor Integration - Ready-made utilities for AI assistants

• Node.js 16+
• Home Assistant instance (or you can use the mock implementations for testing)

# 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

# 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

Configure the server using environment variables or a .env file:

# 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=*

The MCP server is built with a layered architecture:

1. Transport Layer - Handles communication protocols (stdio, HTTP)
2. Middleware Layer - Processes requests through a pipeline
3. Tool Layer - Implements specific functionality
4. Resource Layer - Manages stateful resources

Tools are the primary way to add functionality to the MCP server. Each tool:

• Has a unique name
• Accepts typed parameters
• Returns typed results
• Can stream partial results
• Validates inputs and outputs

Example tool registration:

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());

When running with HTTP transport, the server provides a JSON-RPC 2.0 API:

• POST /api/mcp/jsonrpc - Execute a tool
• GET /api/mcp/stream - Connect to SSE stream for real-time updates
• GET /api/mcp/info - Get server information
• GET /health - Health check endpoint

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
});

To use the Home Assistant MCP server with Cursor, add the following to your .cursor/config/config.json file:

{
  "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"
      }
    }
  }
}

This configuration:

1. Runs the MCP server with stdio transport
2. Redirects all stderr output to /dev/null
3. Uses grep to filter stdout for lines containing {"jsonrpc":"2.0", ensuring clean JSON-RPC output

If you encounter a "failed to create client" error when using the MCP server with Cursor:

1. Make sure you're using the correct command and arguments in your Cursor configuration

   • The bash script approach ensures only valid JSON-RPC messages reach Cursor
   • Ensure the server is built by running bun run build before trying to connect

2. Ensure the server is properly outputting JSON-RPC messages to stdout:

   bun run dist/index.js --stdio 2>/dev/null | grep -E '\{"jsonrpc":"2\.0"' > json_only.txt

   Then examine json_only.txt to verify it contains only valid JSON-RPC messages.

3. Make sure grep is installed on your system (it should be available by default on most systems)

4. Try rebuilding the server with:

   bun run build

5. Enable debug mode by setting DEBUG_STDIO=true in the environment variables

If the issue persists, you can try:

1. Restarting Cursor
2. Clearing Cursor's cache (Help > Developer > Clear Cache and Reload)
3. Using a similar approach with Node.js:

   {
     "command": "bash",
     "args": ["-c", "cd ${workspaceRoot} && node dist/index.js --stdio 2>/dev/null | grep -E '\\{\"jsonrpc\":\"2\\.0\"'"]
   }

MIT

Contributions are welcome! Please feel free to submit a Pull Request.

MCP (Model Context Protocol) Server is my lightweight integration tool for Home Assistant, providing a flexible interface for device management and automation. It's designed to be fast, secure, and easy to use. Built with Bun for maximum performance.

• 🔌 Basic device control via REST API
• 📡 WebSocket/Server-Sent Events (SSE) for state updates
• 🤖 Simple automation rule management
• 🔐 JWT-based authentication
• 🔄 Standard I/O (stdio) transport for integration with Claude and other AI assistants

I chose Bun as the runtime for several key benefits:

• ⚡ Blazing Fast Performance

  • Up to 4x faster than Node.js
  • Built-in TypeScript support
  • Optimized file system operations

• 🎯 All-in-One Solution

  • Package manager (faster than npm/yarn)
  • Bundler (no webpack needed)
  • Test runner (built-in testing)
  • TypeScript transpiler

• 🔋 Built-in Features

  • SQLite3 driver
  • .env file loading
  • WebSocket client/server
  • File watcher
  • Test runner

• 💾 Resource Efficient

  • Lower memory usage
  • Faster cold starts
  • Better CPU utilization

• 🔄 Node.js Compatibility

  • Runs most npm packages
  • Compatible with Express/Fastify
  • Native Node.js APIs

• 🚀 Bun runtime (v1.0.26+)
• 🏡 Home Assistant instance
• 🐳 Docker (optional, recommended for deployment)
• 🖥️ Node.js 18+ (optional, for speech features)
• 🎮 NVIDIA GPU with CUDA support (optional, for faster speech processing)

1. Clone my repository:

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

2. Set up the environment:

# 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

3. Configure your settings:

• Edit .env file with your Home Assistant details
• Required: Add your HASS_TOKEN (long-lived access token)

4. Build and launch with Docker:

# Standard build
./docker-build.sh

# Launch:
docker compose up -d

My Docker build script (docker-build.sh) supports different configurations:

./docker-build.sh

• Basic MCP server functionality
• REST API and WebSocket support
• No speech features

./docker-build.sh --speech

• Includes wake word detection
• Speech-to-text capabilities
• Pulls required images:
  • onerahmet/openai-whisper-asr-webservice
  • rhasspy/wyoming-openwakeword

./docker-build.sh --speech --gpu

• All speech features
• CUDA GPU acceleration
• Optimized for faster processing
• Float16 compute type for better performance

• 🔄 Automatic resource allocation
• 💾 Memory-aware building
• 📊 CPU quota management
• 🧹 Automatic cleanup
• 📝 Detailed build logs
• 📊 Build summary and status

I've implemented a hierarchical configuration system:

1. .env.example - My template with all options
2. .env - Your configuration (copy from .env.example)
3. Environment overrides:
   • .env.dev - Development settings
   • .env.prod - Production settings
   • .env.test - Test settings

Files load in this order:

1. .env (base config)
2. Environment-specific file:
   • NODE_ENV=development → .env.dev
   • NODE_ENV=production → .env.prod
   • NODE_ENV=test → .env.test

Later files override earlier ones.

# 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

• Configuration Guide
• API Documentation
• Troubleshooting

• Natural Language Processing - AI-powered automation analysis and control
• Custom Prompts Guide - Create and customize AI behavior
• Extras & Tools - Additional utilities and advanced features

Add to .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"
      }
    }
  }
}

Add to your Claude config:

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

Windows users can use the provided script:

1. Go to scripts directory
2. Run start_mcp.cmd

MCP Server optionally supports speech processing capabilities:

• 🗣️ Wake word detection ("hey jarvis", "ok google", "alexa")
• 🎯 Speech-to-text using fast-whisper
• 🌍 Multiple language support
• 🚀 GPU acceleration support

1. 🐳 Docker installed and running
2. 🎮 NVIDIA GPU with CUDA (optional)
3. 💾 4GB+ RAM (8GB+ recommended)

1. Enable speech in .env:

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

2. Choose your STT engine:

# For standard Whisper
STT_ENGINE=whisper

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

Choose based on your needs:

• tiny.en: Fastest, basic accuracy
• base.en: Good balance (recommended)
• small.en: Better accuracy, slower
• medium.en: High accuracy, resource intensive
• large-v2: Best accuracy, very resource intensive

# 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

I've included several powerful tools in the extra/ directory to enhance your Home Assistant experience:

1. Home Assistant Analyzer CLI (ha-analyzer-cli.ts)

   • Deep automation analysis using AI models
   • Security vulnerability scanning
   • Performance optimization suggestions
   • System health metrics

2. Speech-to-Text Example (speech-to-text-example.ts)

   • Wake word detection
   • Speech-to-text transcription
   • Multiple language support
   • GPU acceleration support

3. Claude Desktop Setup (claude-desktop-macos-setup.sh)

   • Automated Claude Desktop installation for macOS
   • Environment configuration
   • MCP integration setup

See Extras Documentation for detailed usage instructions and examples.

MIT License. See LICENSE for details.

Created by jango-blockchained

MCP Server supports a JSON-RPC 2.0 stdio transport mode for direct integration with AI assistants like Claude:

✅ JSON-RPC 2.0 Compatibility: Full support for the MCP protocol standard
✅ NPX Support: Run directly without installation using npx homeassistant-mcp
✅ Auto Configuration: Creates necessary directories and default configuration
✅ Cross-Platform: Works on macOS, Linux, and Windows
✅ Claude Desktop Integration: Ready to use with Claude Desktop
✅ Parameter Validation: Automatic validation of tool parameters
✅ Error Handling: Standardized error codes and handling
✅ Detailed Logging: Logs to files without polluting stdio

Run the MCP server directly without installation using npx:

# Basic usage
npx homeassistant-mcp

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

This will:

1. Install the package temporarily
2. Automatically run in stdio mode with JSON-RPC 2.0 transport
3. Create a logs directory for logging
4. Create a default .env file if not present

Perfect for integration with Claude Desktop or other MCP clients.

To use MCP with Claude Desktop:

1. Open Claude Desktop settings
2. Go to the "Advanced" tab
3. Under "MCP Server", select "Custom"
4. Enter the command: npx homeassistant-mcp
5. Click "Save"

Claude will now use the MCP server for Home Assistant integration, allowing you to control your smart home directly through Claude.

1. Update your .env file to enable stdio transport:

   USE_STDIO_TRANSPORT=true
   

2. Run the server using the stdio-start script:

   ./stdio-start.sh

   Available options:

   ./stdio-start.sh --debug    # Enable debug mode
   ./stdio-start.sh --rebuild  # Force rebuild
   ./stdio-start.sh --help     # Show help
   

When running in stdio mode:

• The server communicates via stdin/stdout using JSON-RPC 2.0 format
• No HTTP server is started
• Console logging is disabled to avoid polluting the stdio stream
• All logs are written to the log files in the logs/ directory

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

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

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

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

To use this MCP server with Claude Desktop:

1. Create or edit your Claude Desktop configuration:

   # 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

2. Add the MCP server configuration:

   {
     "mcpServers": {
       "homeassistant-mcp": {
         "command": "npx",
         "args": ["homeassistant-mcp"],
         "env": {
           "HASS_TOKEN": "your_home_assistant_token_here",
           "HASS_HOST": "http://your_home_assistant_host:8123"
         }
       }
     }
   }

3. Restart Claude Desktop.

4. In Claude, you can now use the Home Assistant MCP tools.

The simplest way to use the Home Assistant MCP server is through NPX:

# Start the server in stdio mode
npx homeassistant-mcp

This will automatically:

1. Start the server in stdio mode
2. Output JSON-RPC messages to stdout
3. Send log messages to stderr
4. Create a logs directory if it doesn't exist

You can redirect stderr to hide logs and only see the JSON-RPC output:

npx homeassistant-mcp 2>/dev/null

If you prefer to install the package globally or locally:

# Install globally
npm install -g homeassistant-mcp

# Then run
homeassistant-mcp

Or install locally:

# Install locally
npm install homeassistant-mcp

# Then run using npx
npx homeassistant-mcp