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

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:

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:
```bash
# Standard build
./docker-build.sh

# Launch:
docker compose 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.

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 📊

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:

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

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:

   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

##### 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
```bash
# 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

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