homeassistant-mcp

by tevonsb

211 stars

9 downloads

Not rated

GitHub

About

Access Home Assistant data and control devices (lights, switches, thermostats, etc).

Details

Author: tevonsb
Repository: tevonsb/homeassistant-mcp
GitHub stars: 211
Downloads: 9
License: Apache License 2.0
Categories: Project Management, AI
Tags: #data

- 🎮 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

Setting up with Highlight

Follow these steps to add this server as a custom Highlight plugin:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name homeassistant-mcp

Command (node, npx, python, etc.) node
Arguments
- Argument 1 <path/to/your/dist/folder>
Environment
- PORT 3000
- NODE_ENV development
- HASS_HOST http://homeassistant.local:8123
- LOG_LEVEL debug
- HASS_TOKEN your_home_assistant_token
- HASS_SOCKET_URL ws://homeassistant.local:8123/api/websocket
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

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.

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

1. Clone the repository:

bash
git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp



2. Configure environment:

bash
cp .env.example .env

    Edit the .env file with your Home Assistant configuration:

env

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

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

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

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)


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

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

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

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

`turn_on`

Turns on a specified entity, such as a light. Parameters: entity_id (string), brightness (optional integer), color_temp (optional integer), rgb_color (optional array of integers)

`turn_off`

Turns off a specified entity. Parameters: entity_id (string)

`toggle`

Toggles the state of a specified entity. Parameters: entity_id (string)

`list`

Lists available add-ons.

`install`

Installs a specified add-on. Parameters: slug (string), version (string)

`start`

Starts a specified add-on. Parameters: slug (string)

`stop`

Stops a specified add-on. Parameters: slug (string)

`restart`

Restarts a specified add-on. Parameters: slug (string)

`list`

Lists HACS packages by category. Parameters: category (string)

`install`

Installs a specified package from HACS. Parameters: category (string), repository (string), version (string)

`create`

Creates a new automation. Parameters: config (object)

`duplicate`

Duplicates an existing automation. Parameters: automation_id (string)

`execute_action`

Executes a specified action with given parameters. Parameters: action (string), parameters (object)

`batch_actions`

Executes multiple actions in sequence. Parameters: actions (array of objects)

`get_available_actions`

Returns a list of all available actions.

`context_query`

Retrieves context information. Parameters: type (string)

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

Linux

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

Macos

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

Windows

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

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

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
- Device Control
- Add-on Management
- Package Management
- Automation Management
- 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/tevonsb/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.

1. Clone the repository:

    git clone https://github.com/tevonsb/homeassistant-mcp.git

    cd homeassistant-mcp

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

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

Docker Compose Environment Variables

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)

…

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

turn_on

turn_off

toggle

list

install

start

stop

restart

list

install

create

duplicate

execute_action

batch_actions

get_available_actions

context_query

Claude Desktop / Cursor

Linux

Macos

Windows

Model Context Protocol Server for Home Assistant

Features

Real-time Updates with SSE

Quick SSE Example

Table of Contents

Key Features

Core Functionality 🎮

System Management 🛠️

Architecture Features 🏗️

Prerequisites

Installation

Basic Setup

Install dependencies

Build the project

Docker Setup (Recommended)

Docker Configuration

Docker Compose Environment Variables

Configuration

Environment Variables

Server Configuration

Test Configuration

Configuration Files

Adding to Claude Desktop (or other clients)

Install

More like this

Context 7

1Panel

🔎 GPT Researcher

Serena

FastMCP v2 🚀

MaxKB

`turn_on`

`turn_off`

`toggle`

`list`

`install`

`start`

`stop`

`restart`

`list`

`install`

`create`

`duplicate`

`execute_action`

`batch_actions`

`get_available_actions`

`context_query`