hpohlmann/home-assistant-mcp

A Model Context Protocol (MCP) integration for controlling Home Assistant devices using AI assistants.
## Overview
This MCP allows AI assistants to control your Home Assistant devices. It provides tools to:
1. Search for entities in your Home Assistant instance
2. Control devices (turn them on/off)
3. Control light colors and brightness
## Prerequisites
Python 3.11 or higher
Home Assistant instance running and accessible via API
Home Assistant Long-Lived Access Token
## Installation
### Installing via Smithery
To install Home Assistant Integration for Claude Desktop automatically via Smithery:
bash
npx -y @smithery/cli install @hpohlmann/home-assistant-mcp --client claude
### Manual Installation
1. Clone this repository
2. Set up a Python environment:
bash
cd home-assistant
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -U pip
pip install uv
uv pip install -e .
## Configuration
### Get a Home Assistant Long-Lived Access Token
1. Go to your Home Assistant instance
2. Navigate to your profile (click on your username in the sidebar)
3. Scroll down to "Long-Lived Access Tokens"
4. Create a new token with a descriptive name like "MCP Integration"
5. Copy the token (you'll only see it once)
### Set up in Cursor AI
Add the following configuration to your MCP configuration in Cursor:
json
"mcpServers": {
"homeassistant": {
"command": "uv",
"args": [
"--directory",
"/path/to/your/home-assistant-mcp",
"run",
"main.py"
],
"env": {
"HOMEASSISTANTTOKEN": "yourhomeassistanttokenhere"
},
"inheritEnv": true
Replace:
/path/to/your/home-assistant with the actual path to this directory
yourhomeassistanttokenhere with your Home Assistant Long-Lived Access Token
### Home Assistant URL Configuration
By default, the MCP tries to connect to Home Assistant at http://homeassistant.local:8123.
If your Home Assistant is at a different URL, you can modify the HAURL variable in app/config.py.
## Usage
Once configured, you can use Cursor AI to control your Home Assistant devices:
Search for devices: "Find my living room lights"
Control devices: "Turn on the kitchen light"
Control light colors: "Set my living room lights to red"
Adjust brightness: "Set my dining room lights to blue at 50% brightness"
### Light Control Features
The MCP now supports advanced light control capabilities:
1. Color Control: Set any RGB color for compatible lights
Specify colors using RGB values (0-255 for each component)
Example: setdevicecolor("light.livingroom", 255, 0, 0) for red
2. Brightness Control: Adjust light brightness
Optional brightness parameter (0-255)
Can be combined with color changes
Example: setdevicecolor("light.diningroom", 0, 0, 255, brightness=128) for medium-bright blue
## Troubleshooting
If you get authentication errors, verify your token is correct and has not expired