playbooks

home / mcp / home assistant mcp server

Home Assistant MCP Server

A Model Context Protocol (MCP) integration that enables AI assistants to search for and control Home Assistant devices through natural language commands in Cursor.

Installation
Add the following to your MCP client configuration file.

Configuration

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

You can control your Home Assistant devices with AI assistants through this MCP server. It lets you search for entities, turn devices on or off, and adjust light colors and brightness, enabling hands-free and conversational control over your smart home.

How to use

With Cursor AI or your preferred MCP client, connect to the Home Assistant MCP server to start controlling your devices. You can search for entities by natural language, for example asking to find living room lights. You can turn devices on or off, adjust light colors, and set brightness levels. The server exposes functions to set RGB colors for compatible lights and to apply brightness in a single action. Use simple commands and your assistant will perform the actions in Home Assistant.

How to install

Prerequisites you need before installing: - Python 3.11 or higher - Home Assistant instance running and accessible via API - Home Assistant Long-Lived Access Token - A machine to run the MCP server (your choice of runtime)

# Quick install via Smithery (automatic)
npx -y @smithery/cli install @hpohlmann/home-assistant-mcp --client claude

Manual installation steps if you prefer to set up the MCP server locally: 1) Create a Python virtual environment and install dependencies 2) Install the MCP package in editable mode 3) Run the MCP server with the appropriate token 4) Point your MCP client to the running server (see configuration) 

# Example manual setup
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 from your Home Assistant profile. Create a token with a descriptive name like "MCP Integration" and copy it (it is shown only once).

Set up in Cursor AI by providing the MCP server configuration that runs the server locally and uses your token for authentication.

{
  "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
    }
  }
}

Note that the MCP will attempt to connect to Home Assistant at the default URL http://homeassistant.local:8123. If your instance uses a different URL, adjust the HA URL in the configuration accordingly.

Troubleshooting

If you encounter authentication errors, verify your token is correct and has not expired. Ensure your Home Assistant instance is reachable at the configured URL. For color control issues, confirm the target light supports RGB color control, and that the light is turned on when applying color changes.

Notes

Future enhancements may include more dynamic exposure of entities, direct natural-language control of devices, caching for faster responses, and expanded support for brightness, temperature, and complex entity groups.

Available tools

find_entities

Search for Home Assistant entities by natural language phrases to locate the specific device or entity you want to control.

control_device

Turn a device on or off, or adjust attributes like brightness or state.

set_device_color

Set RGB color for lights that support color control and optionally adjust brightness in the same command.