MCP Server for Home Assistant 🏠🤖

Overview 🌐

MCP (Model Context Protocol) Server is a lightweight integration tool for Home Assistant, providing a flexible interface for device management and automation.

Core Features ✨

• 🔌 Basic device control via REST API
• 📡 WebSocket/Server-Sent Events (SSE) for state updates
• 🤖 Simple automation rule management
• 🔐 JWT-based authentication

Prerequisites 📋

• 🚀 Bun runtime (v1.0.26+)
• 🏡 Home Assistant instance
• 🐳 Docker (optional, recommended for deployment)

Installation 🛠️

Docker Deployment (Recommended)

# Clone the repository
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp

# Copy and edit environment configuration
cp .env.example .env
# Edit .env with your Home Assistant credentials

# Build and start containers
docker compose up -d --build

Bare Metal Installation

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Clone the repository
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp

# Install dependencies
bun install

# Start the server
bun run dev

Basic Usage 🖥️

Device Control Example

// Turn on a light
const response = await fetch('http://localhost:3000/api/devices/light.living_room', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({ state: 'on' })
});

WebSocket State Updates

const ws = new WebSocket('ws://localhost:3000/devices');
ws.onmessage = (event) => {
  const deviceState = JSON.parse(event.data);
  console.log('Device state updated:', deviceState);
};

Current Limitations ⚠️

• 🎙️ Basic voice command support (work in progress)
• 🧠 Limited advanced NLP capabilities
• 🔗 Minimal third-party device integration
• 🐛 Early-stage error handling

Contributing 🤝

1. Fork the repository
2. Create a feature branch:

   git checkout -b feature/your-feature
   

3. Make your changes
4. Run tests:

   bun test
   

5. Submit a pull request

Roadmap 🗺️

• 🎤 Enhance voice command processing
• 🔌 Improve device compatibility
• 🤖 Expand automation capabilities
• 🛡️ Implement more robust error handling

License 📄

MIT License. See LICENSE for details.

Support 🆘

• 🐞 GitHub Issues
• 📖 Documentation: Project Docs

MCP Client Integration 🔗

This MCP server can be integrated with various clients that support the Model Context Protocol. Below are instructions for different client integrations:

Cursor Integration 🖱️

The server can be integrated with Cursor by adding the configuration to .cursor/config/config.json:

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

Claude Desktop Integration 💬

For Claude Desktop, add the following to your Claude configuration file:

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

Cline Integration 📟

For Cline-based clients, add the following configuration:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bun",
      "args": [
        "run",
        "start",
        "--enable-cline",
        "--config",
        "${configDir}/.env"
      ],
      "env": {
        "NODE_ENV": "production",
        "CLINE_MODE": "true"
      }
    }
  }
}

Command Line Usage 💻

Windows

A CMD script is provided in the scripts directory. To use it:

1. Navigate to the scripts directory
2. Run start_mcp.cmd

The script will start the MCP server with default configuration.