Home Assistant Integration

🚀 Home Assistant MCP

A Model Context Protocol (MCP) integration for controlling Home Assistant devices via an AI assistant.

🚀 Quick Start

This MCP allows an AI assistant to control your Home Assistant devices. It offers the following capabilities:

1. Search for entities within your Home Assistant instance.
2. Control devices (turn on/off).
3. Control the color and brightness of lights.

✨ Features

• Entity Search: Search for entities in your Home Assistant instance.
• Device Control: Turn devices on or off.
• Light Control: Adjust the color and brightness of lights.
• Advanced Light Control: Set any RGB color for compatible lights and adjust brightness.

📦 Installation

Prerequisites

• Python 3.11 or higher.
• A running Home Assistant instance accessible via API.
• A Home Assistant long - lived access token.

Steps

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

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 .

📚 Documentation

Configuration

Obtain 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 to the bottom to "Long - Lived Access Tokens".
4. Create a new token with a descriptive name, e.g., "MCP Integration".
5. Copy the token (you'll only see it at creation time).

Set up in Cursor AI

Add the following configuration to your MCP configuration:

{
  "mcpServers": {
    "home_assistant": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/home-assistant-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "HOME_ASSISTANT_TOKEN": "your_home_assistant_token_here"
      },
      "inheritEnv": true
    }
  }
}

Replace:

• /path/to/your/home-assistant with the actual path to your Home Assistant directory.
• your_home_assistant_token_here with your long - lived Home Assistant access token.

Home Assistant URL Configuration

By default, MCP attempts to connect to Home Assistant at http://homeassistant.local:8123. If your Home Assistant is located at a different URL, you can modify the HA_URL variable in app/config.py.

Usage

After configuration, you can use Cursor AI to control your Home Assistant devices:

• Search for devices: For example, "Find my living room light".
• Control devices: For example, "Turn on the kitchen light".
• Control light color: For example, "Set my living room light to red".
• Adjust brightness: For example, "Set my dining room light to blue at 50% brightness".

💻 Usage Examples

Basic Usage

# Search for a device
# This is a conceptual example and the actual implementation may vary
search_result = search_entity("living room light")

Advanced Usage

# Set the color and brightness of a light
set_device_color("light.dining_room", 0, 0, 255, brightness=128)

🔧 Technical Details

Light Control Features

MCP now supports advanced light control features:

1. Color Control: Set any RGB color for compatible lights.
   • Specify the color using RGB values (0 - 255 for each component).
   • Example: set_device_color("light.living_room", 255, 0, 0) sets the light to red.
2. Brightness Control: Adjust the brightness of lights.
   • An optional brightness parameter (0 - 255) is available.
   • Can be combined with color changes.
   • Example: set_device_color("light.dining_room", 0, 0, 255, brightness=128) sets the light to medium - brightness blue.

🛠️ Troubleshooting

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

🚧 Future Features

Dynamic Entity Exposure

The current implementation requires a two - step process of searching for an entity using natural language and then controlling the device:

1. Search for an entity using natural language.
2. Control the entity using its specific entity_id. The planned enhancement is to create a more dynamic way to expose entities to MCP for direct control. For example:

• For lights: "Living room light".
• For smart plugs: "Kitchen plug". This will allow MCP to interact directly with devices without first searching for their IDs.