Home Assistant MCP Server

Smart HomePython

Control and query your Home Assistant smart home system through natural language

Available Tools

home_assistant

Interact with Home Assistant to control devices, check sensor states, and manage your smart home

The Home Assistant MCP server enables AI assistants to interact with your smart home devices and sensors through the Model Context Protocol. It connects to your Home Assistant instance via websocket API, allowing you to control lights, check sensor values, manage automations, and more using natural language commands. This integration brings the power of your smart home to conversational AI interfaces like Claude Desktop.

Overview

The Home Assistant MCP server provides a bridge between AI assistants and your Home Assistant smart home system. It allows you to control devices, check sensor states, manage automations, and more through natural language interactions.

Prerequisites

Before setting up the Home Assistant MCP server, you'll need:

A running Home Assistant instance
The home-assistant-model-context-protocol custom component installed in your Home Assistant instance (Note: This is being integrated into Home Assistant Core in PR #134122)
A Long Lived Access Token from your Home Assistant instance

Installation

Clone the repository:

git clone https://github.com/allenporter/mcp-server-home-assistant
cd mcp-server-home-assistant

Install the package:
```
pip install -e .
```
Alternatively, you can use uv for installation:
```
uv pip install -e .
```

Configuration

To use the Home Assistant MCP server with Claude Desktop or other compatible AI assistants, you'll need to:

Create a Long Lived Access Token in Home Assistant:
- Go to your profile in Home Assistant (click on your username in the sidebar)
- Scroll down to the "Long-Lived Access Tokens" section
- Create a new token and save it securely
Configure your AI assistant to use the MCP server by adding it to your configuration file (e.g., claude_desktop_config.json).
Set the following environment variables in your configuration:
- HOME_ASSISTANT_WEB_SOCKET_URL: The websocket URL of your Home Assistant instance (e.g., "http://localhost:8123/api/websocket")
- HOME_ASSISTANT_API_TOKEN: Your Long Lived Access Token

Troubleshooting

If you encounter issues with the MCP server:

Check the logs for detailed error messages:
- On macOS: ~/Library/Logs/Claude/mcp-server-Home-assistant.log
- On other platforms: Check your AI assistant's documentation for log locations
Verify your Home Assistant instance is accessible at the URL you provided
Ensure your access token has the necessary permissions and hasn't expired
Make sure the home-assistant-model-context-protocol custom component is properly installed in your Home Assistant instance