home / mcp / home assistant mcp server

Home Assistant MCP Server

Home Assistant MCP

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ailearncoder-home_assistant_mcp": {
      "command": "home-assistant-mcp",
      "args": [],
      "env": {
        "HOME_ASSISTANT_URL": "http://127.0.0.1:8123",
        "HOME_ASSISTANT_PASSWORD": "admin123",
        "HOME_ASSISTANT_USERNAME": "admin",
        "HOME_ASSISTANT_CACHE_DIR": "./.cache"
      }
    }
  }
}

You can run a lightweight MCP service that connects to Home Assistant to fetch live device context and expose simple controls for groups of devices. It handles long-term token management, auto-installs the mcp_server integration, and lets you batch-control switches and lights through a clean MCP interface.

How to use

Your server runs as an MCP service that connects to Home Assistant via an SSE endpoint and exposes a small set of utilities for downstream MCP clients. You can fetch the latest device context to learn each device’s id and then issue batch commands to turn devices on/off or adjust brightness. Use the provided MCP tools to discover devices first, then apply actions to specific device ids.

How to install

Prerequisites: install Python 3.11 or newer. Ensure you have an active Home Assistant instance reachable at its URL.

Install the MCP server package from the project root directory.

Then start the MCP service using the built-in entry point. The recommended command is the one you use to launch the service directly as an MCP server process.

Configuration and runtime notes

Environment variables control how you connect to Home Assistant and where tokens are cached. You can override defaults as needed.

Troubleshooting

Authentication errors usually relate to the token cache or incorrect Home Assistant credentials. Delete the cached token and try again, ensuring HOME_ASSISTANT_URL points to your Home Assistant instance. If SSE connectivity fails, verify the mcp_server integration is installed and enabled in Home Assistant and that the network path to Home Assistant is reachable.

Security and maintenance

Do not commit real tokens to version control. Place sensitive values in environment variables and cache them in a local directory. For production, prefer secure WebSocket endpoints (wss) and strong credentials.

Notes

The server exposes a small set of tools for downstream clients, including device discovery and simple control actions. Use the tools to retrieve device ids, then apply switches or brightness settings to those ids.

Available tools

get_device_info

Refresh and return the list of devices with their ids, names, areas, and related metadata.

switch_control

Control a list of devices by id to turn them on or off in bulk.

light_set

Set brightness levels (0-100) for a list of devices by id; a value of None turns the device off.