Home Assistant Model Context Protocol (MCP)

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

Overview

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

Features

• 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

Getting Started

Prerequisites

• Node.js 16+

• Home Assistant instance (or you can use the mock implementations for testing)

Installation

Running the Server

Configuration

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

Architecture

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

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:

API

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

Integration with AI Models

Claude Integration

Cursor Integration

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

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

Troubleshooting Cursor Integration

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\"'"] }

License

MIT

Contributing

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

MCP Server for Home Assistant 🏠🤖

Overview 🌐

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.

Core Features ✨

• 🔌 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

Why Bun? 🚀

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

Prerequisites 📋

• 🚀 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)

Quick Start 🚀

1. Clone my repository:

2. Set up the environment:

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:

Docker Build Options 🐳

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

1. Standard Build

• Basic MCP server functionality

• REST API and WebSocket support

• No speech features

2. Speech-Enabled Build

• Includes wake word detection

• Speech-to-text capabilities

• Pulls required images:

  • onerahmet/openai-whisper-asr-webservice

  • rhasspy/wyoming-openwakeword

3. GPU-Accelerated Build

• All speech features

• CUDA GPU acceleration

• Optimized for faster processing

• Float16 compute type for better performance

Build Features

• 🔄 Automatic resource allocation

• 💾 Memory-aware building

• 📊 CPU quota management

• 🧹 Automatic cleanup

• 📝 Detailed build logs

• 📊 Build summary and status

Environment Configuration 🔧

I've implemented a hierarchical configuration system:

File Structure 📁

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

Loading Priority ⚡

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.

Development 💻

Performance Comparison 📊

Documentation 📚

Core Documentation

• Configuration Guide

• API Documentation

• Troubleshooting

Advanced Features

• Natural Language Processing - AI-powered automation analysis and control

• Custom Prompts Guide - Create and customize AI behavior

• Extras & Tools - Additional utilities and advanced features

Client Integration 🔗

Cursor Integration 🖱️

Add to .cursor/config/config.json:

Claude Desktop 💬

Add to your Claude config:

Command Line 💻

Windows users can use the provided script:

1. Go to scripts directory

2. Run start_mcp.cmd

Additional Features

Speech Features 🎤

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

Speech Features Setup

Prerequisites

1. 🐳 Docker installed and running

2. 🎮 NVIDIA GPU with CUDA (optional)

3. 💾 4GB+ RAM (8GB+ recommended)

Configuration

1. Enable speech in .env:

2. Choose your STT engine:

Available Models 🤖

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

Launch with Speech Features

Extra Tools 🛠️

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.

License 📄

MIT License. See LICENSE for details.

Author 👨‍💻

Created by jango-blockchained

Running with Standard I/O Transport 📝

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

MCP Stdio Features

✅ 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

Option 1: Using NPX (Easiest)

Run the MCP server directly without installation using npx:

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.

Integrating with Claude Desktop

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.

Option 2: Local Installation

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

JSON-RPC 2.0 Message Format

Request Format

Response Format

Error Response Format

Notification Format (Server to Client)

Supported Error Codes

Integrating with Claude Desktop

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.

JSON-RPC 2.0 Message Format

Usage

Using NPX (Easiest)

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

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:

Manual Installation

If you prefer to install the package globally or locally:

Or install locally:

Advanced Usage