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

1. Clone this repository
2. Set up a Python environment:

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:

Replace:

• /path/to/your/home-assistant with the actual path to this directory
• your_home_assistant_token_here 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 HA_URL 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: set_device_color("light.living_room", 255, 0, 0) for red
2. Brightness Control: Adjust light brightness
   • Optional brightness parameter (0-255)
   • Can be combined with color changes
   • Example: set_device_color("light.dining_room", 0, 0, 255, brightness=128) for medium-bright blue

Troubleshooting

• If you get authentication errors, verify your token is correct and has not expired
• Check that your Home Assistant instance is reachable at the configured URL
• For color control issues:
  • Verify that your light entity supports RGB color control
  • Check that the light is turned on before attempting to change colors

Future Capabilities

Dynamic Entity Exposure

The current implementation requires a two-step process to control devices:

1. Search for entities using natural language
2. Control the entity using its specific entity_id

A planned enhancement is to create a more dynamic way to expose entities to the control devices tool, allowing the AI to:

• Directly control devices through more natural commands (e.g., "turn off the kitchen lights")
• Cache frequently used entities for faster access
• Support more complex operations like adjusting brightness, temperature, or other attributes
• Handle entity groups and scenes more intuitively

This would significantly reduce the time to action and create a more seamless user experience when controlling Home Assistant devices through an AI assistant.