Homeassistant MCP

What is Homeassistant MCP about?

Homeassistant MCP bridges a Home Assistant instance with language models, offering a full‑featured API for device control, state monitoring, automation management, add‑on handling, and package management. It delivers real‑time updates via Server‑Sent Events (SSE) and optional WebSocket streams, all secured with token‑based authentication and rate limiting.

How to use Homeassistant MCP?

Prerequisites – Node.js ≥20.10, Docker Compose (optional), a running Home Assistant with a long‑lived access token, and HACS installed for package features.

Installation – Clone the repo, run npm install, then npm run build. For production, use Docker:

git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp
cp .env.example .env   # edit with your HA details
docker compose up -d

Running – The server listens on the configured PORT (default 3000). Access health at http://localhost:3000/health.
Authentication – Include the Home Assistant long‑lived token as a token query parameter or in the Authorization: ApiKey <TOKEN> header for each request.

API Calls – Use the documented REST endpoints (/api/state, /api/action, etc.) or open an SSE stream:

const es = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light');
es.onmessage = e => console.log(JSON.parse(e.data));

Key features of Homeassistant MCP

Device Control – Lights, climate, covers, switches, sensors, media players, fans, locks, vacuums, cameras, and more.
Real‑time Updates – SSE (and planned WebSocket) streams for state changes, automation triggers, service calls.
Automation Management – Create, edit, duplicate, enable/disable, and manually trigger automations with complex triggers and actions.
Add‑on Management – List, install, start, stop, restart, and configure Home Assistant add‑ons via the Supervisor API.
Package Management (HACS) – Browse, install, update, and manage integrations, themes, Python scripts, AppDaemon/NetDaemon apps.
Secure API – Token authentication, configurable rate limits, comprehensive error handling.
Dockerized Deployment – Multi‑stage image, health checks, environment variable support, automatic restart.
TypeScript & Test Coverage – Strong type safety, extensive Jest tests (~95% coverage).

Use cases of Homeassistant MCP

Voice/LLM assistants – Connect ChatGPT, Claude, or custom LLMs to control lights, adjust temperature, or run scenes using natural language.
Mobile/Web dashboards – Build lightweight clients that receive live updates without polling.
Automation scripting – Programmatically create complex automations from external systems or CI pipelines.
Add‑on orchestration – Automate the lifecycle of Home Assistant add‑ons (install, upgrade, restart) from scripts.
Package deployment – Manage HACS repositories and update community integrations across multiple HA instances.

FAQ from the Homeassistant MCP

Q: Do I need Docker to run the server? A: No. You can run it locally with Node (npm run dev or npm start). Docker is provided for consistent production deployments.

Q: How is authentication handled? A: The server expects the Home Assistant long‑lived access token either as a token query parameter or in the Authorization: ApiKey <TOKEN> header.

Q: Can I get real‑time state changes? A: Yes, via the SSE endpoint /subscribe_events. WebSocket support is in progress.

Q: What rate limits are applied? A: 100 requests per minute per IP for regular endpoints and 1000 per minute for WebSocket connections. Exceeding limits returns a RATE_LIMIT_EXCEEDED error.

Q: Is the server compatible with all Home Assistant versions? A: It requires a Home Assistant instance with the Supervisor API (for add‑on management) and HACS installed for package features. It works with recent stable releases.

Model Context Protocol Server for Home Assistant

The server uses the MCP protocol to share access to a local Home Assistant instance with an LLM application.

A powerful bridge between your Home Assistant instance and Language Learning Models (LLMs), enabling natural language control and monitoring of your smart home devices through the Model Context Protocol (MCP). This server provides a comprehensive API for managing your entire Home Assistant ecosystem, from device control to system administration.

Features

🎮 Device Control: Control any Home Assistant device through natural language
🔄 Real-time Updates: Get instant updates through Server-Sent Events (SSE)
🤖 Automation Management: Create, update, and manage automations
📊 State Monitoring: Track and query device states
🔐 Secure: Token-based authentication and rate limiting
📱 Mobile Ready: Works with any HTTP-capable client

Real-time Updates with SSE

The server includes a powerful Server-Sent Events (SSE) system that provides real-time updates from your Home Assistant instance. This allows you to:

🔄 Get instant state changes for any device
📡 Monitor automation triggers and executions
🎯 Subscribe to specific domains or entities
📊 Track service calls and script executions

Quick SSE Example

const eventSource = new EventSource(
  'http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light'
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Update received:', data);
};

See SSE_API.md for complete documentation of the SSE system.

Key Features
Prerequisites
Installation
- Basic Setup
- Docker Setup (Recommended)
Configuration
Development
API Reference
Natural Language Integration
Troubleshooting
Project Status
Contributing
Resources
License

Key Features

Core Functionality 🎮

Smart Device Control
- 💡 Lights: Brightness, color temperature, RGB color
- 🌡️ Climate: Temperature, HVAC modes, fan modes, humidity
- 🚪 Covers: Position and tilt control
- 🔌 Switches: On/off control
- 🚨 Sensors & Contacts: State monitoring
- 🎵 Media Players: Playback control, volume, source selection
- 🌪️ Fans: Speed, oscillation, direction
- 🔒 Locks: Lock/unlock control
- 🧹 Vacuums: Start, stop, return to base
- 📹 Cameras: Motion detection, snapshots

System Management 🛠️

Add-on Management
- Browse available add-ons
- Install/uninstall add-ons
- Start/stop/restart add-ons
- Version management
- Configuration access
Package Management (HACS)
- Integration with Home Assistant Community Store
- Multiple package types support:
  - Custom integrations
  - Frontend themes
  - Python scripts
  - AppDaemon apps
  - NetDaemon apps
- Version control and updates
- Repository management
Automation Management
- Create and edit automations
- Advanced configuration options:
  - Multiple trigger types
  - Complex conditions
  - Action sequences
  - Execution modes
- Duplicate and modify existing automations
- Enable/disable automation rules
- Trigger automation manually

Architecture Features 🏗️

Intelligent Organization
- Area and floor-based device grouping
- State monitoring and querying
- Smart context awareness
- Historical data access
Robust Architecture
- Comprehensive error handling
- State validation
- Secure API integration
- TypeScript type safety
- Extensive test coverage

Prerequisites

Node.js 20.10.0 or higher
NPM package manager
Docker Compose for containerization
Running Home Assistant instance
Home Assistant long-lived access token (How to get token)
HACS installed for package management features
Supervisor access for add-on management

Installation

Basic Setup

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

# Install dependencies
npm install

# Build the project
npm run build

Docker Setup (Recommended)

The project includes Docker support for easy deployment and consistent environments across different platforms.

Clone the repository:

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

Configure environment:

cp .env.example .env

Edit the .env file with your Home Assistant configuration:

# Home Assistant Configuration
HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=your_home_assistant_token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket

# Server Configuration
PORT=3000
NODE_ENV=production
DEBUG=false

Build and run with Docker Compose:

# Build and start the containers
docker compose up -d

# View logs
docker compose logs -f

# Stop the service
docker compose down

Verify the installation: The server should now be running at http://localhost:3000. You can check the health endpoint at http://localhost:3000/health.

Update the application:

# Pull the latest changes
git pull

# Rebuild and restart the containers
docker compose up -d --build

Docker Configuration

The Docker setup includes:

Multi-stage build for optimal image size
Health checks for container monitoring
Volume mounting for environment configuration
Automatic container restart on failure
Exposed port 3000 for API access

Docker Compose Environment Variables

All environment variables can be configured in the .env file. The following variables are supported:

HASS_HOST: Your Home Assistant instance URL
HASS_TOKEN: Long-lived access token for Home Assistant
HASS_SOCKET_URL: WebSocket URL for Home Assistant
PORT: Server port (default: 3000)
NODE_ENV: Environment (production/development)
DEBUG: Enable debug mode (true/false)

Configuration

Environment Variables

# Home Assistant Configuration
HASS_HOST=http://homeassistant.local:8123  # Your Home Assistant instance URL
HASS_TOKEN=your_home_assistant_token       # Long-lived access token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket  # WebSocket URL

# Server Configuration
PORT=3000                # Server port (default: 3000)
NODE_ENV=production     # Environment (production/development)
DEBUG=false            # Enable debug mode

# Test Configuration
TEST_HASS_HOST=http://localhost:8123  # Test instance URL
TEST_HASS_TOKEN=test_token           # Test token

Configuration Files

Development: Copy .env.example to .env.development
Production: Copy .env.example to .env.production
Testing: Copy .env.example to .env.test

Adding to Claude Desktop (or other clients)

To use your new Home Assistant MCP server, you can add Claude Desktop as a client. Add the following to the configuration. Note this will run the MCP within claude and does not work with the Docker method.

{
  "homeassistant": {
    "command": "node",
    "args": [<path/to/your/dist/folder>]
    "env": {
      NODE_ENV=development
      HASS_HOST=http://homeassistant.local:8123
      HASS_TOKEN=your_home_assistant_token
      PORT=3000
      HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
      LOG_LEVEL=debug
    }
  }
}

API Reference

Device Control

Common Entity Controls

{
  "tool": "control",
  "command": "turn_on",  // or "turn_off", "toggle"
  "entity_id": "light.living_room"
}

Light Control

{
  "tool": "control",
  "command": "turn_on",
  "entity_id": "light.living_room",
  "brightness": 128,
  "color_temp": 4000,
  "rgb_color": [255, 0, 0]
}

Add-on Management

List Available Add-ons

{
  "tool": "addon",
  "action": "list"
}

Install Add-on

{
  "tool": "addon",
  "action": "install",
  "slug": "core_configurator",
  "version": "5.6.0"
}

Manage Add-on State

{
  "tool": "addon",
  "action": "start",  // or "stop", "restart"
  "slug": "core_configurator"
}

Package Management

List HACS Packages

{
  "tool": "package",
  "action": "list",
  "category": "integration"  // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}

Install Package

{
  "tool": "package",
  "action": "install",
  "category": "integration",
  "repository": "hacs/integration",
  "version": "1.32.0"
}

Automation Management

Create Automation

{
  "tool": "automation_config",
  "action": "create",
  "config": {
    "alias": "Motion Light",
    "description": "Turn on light when motion detected",
    "mode": "single",
    "trigger": [
      {
        "platform": "state",
        "entity_id": "binary_sensor.motion",
        "to": "on"
      }
    ],
    "action": [
      {
        "service": "light.turn_on",
        "target": {
          "entity_id": "light.living_room"
        }
      }
    ]
  }
}

Duplicate Automation

{
  "tool": "automation_config",
  "action": "duplicate",
  "automation_id": "automation.motion_light"
}

Core Functions

State Management

GET /api/state
POST /api/state

Manages the current state of the system.

Example Request:

POST /api/state
{
  "context": "living_room",
  "state": {
    "lights": "on",
    "temperature": 22
  }
}

Context Updates

POST /api/context

Updates the current context with new information.

Example Request:

POST /api/context
{
  "user": "john",
  "location": "kitchen",
  "time": "morning",
  "activity": "cooking"
}

Action Endpoints

Execute Action

POST /api/action

Executes a specified action with given parameters.

Example Request:

POST /api/action
{
  "action": "turn_on_lights",
  "parameters": {
    "room": "living_room",
    "brightness": 80
  }
}

Batch Actions

POST /api/actions/batch

Executes multiple actions in sequence.

Example Request:

POST /api/actions/batch
{
  "actions": [
    {
      "action": "turn_on_lights",
      "parameters": {
        "room": "living_room"
      }
    },
    {
      "action": "set_temperature",
      "parameters": {
        "temperature": 22
      }
    }
  ]
}

Query Functions

Get Available Actions

GET /api/actions

Returns a list of all available actions.

Example Response:

{
  "actions": [
    {
      "name": "turn_on_lights",
      "parameters": ["room", "brightness"],
      "description": "Turns on lights in specified room"
    },
    {
      "name": "set_temperature",
      "parameters": ["temperature"],
      "description": "Sets temperature in current context"
    }
  ]
}

Context Query

GET /api/context?type=current

Retrieves context information.

Example Response:

{
  "current_context": {
    "user": "john",
    "location": "kitchen",
    "time": "morning",
    "activity": "cooking"
  }
}

WebSocket Events

The server supports real-time updates via WebSocket connections.

// Client-side connection example
const ws = new WebSocket('ws://localhost:3000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received update:', data);
};

Supported Events

state_change: Emitted when system state changes
context_update: Emitted when context is updated
action_executed: Emitted when an action is completed
error: Emitted when an error occurs

Example Event Data:

{
  "event": "state_change",
  "data": {
    "previous_state": {
      "lights": "off"
    },
    "current_state": {
      "lights": "on"
    },
    "timestamp": "2024-03-20T10:30:00Z"
  }
}

Error Handling

All endpoints return standard HTTP status codes:

200: Success
400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
500: Internal Server Error

Error Response Format:

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Missing required parameter: room",
    "details": {
      "missing_fields": ["room"]
    }
  }
}

Rate Limiting

The API implements rate limiting to prevent abuse:

100 requests per minute per IP for regular endpoints
1000 requests per minute per IP for WebSocket connections

When rate limit is exceeded, the server returns:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "reset_time": "2024-03-20T10:31:00Z"
  }
}

Example Usage

Using curl

# Get current state
curl -X GET \
  http://localhost:3000/api/state \
  -H 'Authorization: ApiKey your_api_key_here'

# Execute action
curl -X POST \
  http://localhost:3000/api/action \
  -H 'Authorization: ApiKey your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "turn_on_lights",
    "parameters": {
      "room": "living_room",
      "brightness": 80
    }
  }'

Using JavaScript

// Execute action
async function executeAction() {
  const response = await fetch('http://localhost:3000/api/action', {
    method: 'POST',
    headers: {
      'Authorization': 'ApiKey your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'turn_on_lights',
      parameters: {
        room: 'living_room',
        brightness: 80
      }
    })
  });
  
  const data = await response.json();
  console.log('Action result:', data);
}

Development

# Development mode with hot reload
npm run dev

# Build project
npm run build

# Production mode
npm run start

# Run tests
npx jest --config=jest.config.cjs

# Run tests with coverage
npx jest --coverage

# Lint code
npm run lint

# Format code
npm run format

Troubleshooting

Common Issues

Node.js Version (toSorted is not a function)
- Solution: Update to Node.js 20.10.0+
```
nvm install 20.10.0
nvm use 20.10.0
```
Connection Issues
- Verify Home Assistant is running
- Check HASS_HOST accessibility
- Validate token permissions
- Ensure WebSocket connection for real-time updates
Add-on Management Issues
- Verify Supervisor access
- Check add-on compatibility
- Validate system resources
HACS Integration Issues
- Verify HACS installation
- Check HACS integration status
- Validate repository access
Automation Issues
- Verify entity availability
- Check trigger conditions
- Validate service calls
- Monitor execution logs

Project Status

✅ Complete

Entity, Floor, and Area access
Device control (Lights, Climate, Covers, Switches, Contacts)
Add-on management system
Package management through HACS
Advanced automation configuration
Basic state management
Error handling and validation
Docker containerization
Jest testing setup
TypeScript integration
Environment variable management
Home Assistant API integration
Project documentation

🚧 In Progress

WebSocket implementation for real-time updates
Enhanced security features
Tool organization optimization
Performance optimization
Resource context integration
API documentation generation
Multi-platform desktop integration
Advanced error recovery
Custom prompt testing
Enhanced macOS integration
Type safety improvements
Testing coverage expansion

Contributing

Fork the repository
Create a feature branch
Implement your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

Resources

License

MIT License - See LICENSE file