HomeAssistant MCP

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.

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

Core Features โœจ

  • ๐Ÿ”Œ Basic device control via REST API
  • ๐Ÿ“ก WebSocket/Server-Sent Events (SSE) for state updates
  • ๐Ÿค– Simple automation rule management
  • ๐Ÿ” JWT-based authentication
  • ๐ŸŽค Optional speech features:
    • ๐Ÿ—ฃ๏ธ Wake word detection ("hey jarvis", "ok google", "alexa")
    • ๐ŸŽฏ Speech-to-text using fast-whisper
    • ๐ŸŒ Multiple language support
    • ๐Ÿš€ GPU acceleration support

System Architecture ๐Ÿ“Š

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:
git clone https://github.com/jango-blockchained/homeassistant-mcp.git cd homeassistant-mcp
  1. 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
  1. Configure your settings:
  • Edit .env file with your Home Assistant details
  • Required: Add your HASS_TOKEN (long-lived access token)
  1. Build and launch with Docker:
# Build options: # Standard build ./docker-build.sh # Build with speech support ./docker-build.sh --speech # Build with speech and GPU support ./docker-build.sh --speech --gpu # Launch: docker compose up -d # With speech features: docker compose -f docker-compose.yml -f docker-compose.speech.yml up -d

Docker Build Options ๐Ÿณ

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

1. Standard Build

./docker-build.sh
  • Basic MCP server functionality
  • REST API and WebSocket support
  • No speech features

2. Speech-Enabled Build

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

3. GPU-Accelerated Build

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

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:
ENABLE_SPEECH_FEATURES=true ENABLE_WAKE_WORD=true ENABLE_SPEECH_TO_TEXT=true WHISPER_MODEL_PATH=/models WHISPER_MODEL_TYPE=base
  1. 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

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

Development ๐Ÿ’ป

# 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

Performance Comparison ๐Ÿ“Š

OperationBunNode.js
Install Dependencies~2s~15s
Cold Start300ms1000ms
Build Time150ms4000ms
Memory Usage~150MB~400MB

Documentation ๐Ÿ“š

Core Documentation

Advanced 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.

Client Integration ๐Ÿ”—

Cursor Integration ๐Ÿ–ฑ๏ธ

Add to .cursor/config/config.json:

{ "mcpServers": { "homeassistant-mcp": { "command": "bun", "args": ["run", "start"], "cwd": "${workspaceRoot}", "env": { "NODE_ENV": "development" } } } }

Claude Desktop ๐Ÿ’ฌ

Add to your Claude config:

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

Command Line ๐Ÿ’ป

Windows users can use the provided script:

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

License ๐Ÿ“„

MIT License. See LICENSE for details.

Author ๐Ÿ‘จโ€๐Ÿ’ป

Created by jango-blockchained