GitHub - tevonsb/homeassistant-mcp: A MCP server for Home Assistant (original) (raw)

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.

License Node.js Docker Compose NPM TypeScript Test Coverage

Features

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:

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.

Table of Contents

Key Features

Core Functionality 🎮

System Management 🛠️

Architecture Features 🏗️

Prerequisites

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

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

  1. Clone the repository:
    git clone https://github.com/jango-blockchained/homeassistant-mcp.git
    cd homeassistant-mcp
  2. Configure environment:
    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 3. 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 4. **Verify the installation:**The server should now be running at http://localhost:3000. You can check the health endpoint at http://localhost:3000/health. 5. 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:

Docker Compose Environment Variables

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

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

  1. Development: Copy .env.example to .env.development
  2. Production: Copy .env.example to .env.production
  3. 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

Updates the current context with new information.

Example Request:

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

Action Endpoints

Execute 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

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

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

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:

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:

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

  1. 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
  2. Connection Issues
    • Verify Home Assistant is running
    • Check HASS_HOST accessibility
    • Validate token permissions
    • Ensure WebSocket connection for real-time updates
  3. Add-on Management Issues
    • Verify Supervisor access
    • Check add-on compatibility
    • Validate system resources
  4. HACS Integration Issues
    • Verify HACS installation
    • Check HACS integration status
    • Validate repository access
  5. Automation Issues
    • Verify entity availability
    • Check trigger conditions
    • Validate service calls
    • Monitor execution logs

Project Status

✅ Complete

🚧 In Progress

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Implement your changes
  4. Add tests for new functionality
  5. Ensure all tests pass
  6. Submit a pull request

Resources

License

MIT License - See LICENSE file