Home Assistant MCP Server
About
Home Assistant MCP Server is a Model Context Protocol (MCP) server for integrating with Home Assistant, enabling LLMs to control and query your smart home via natural language. It works with any MCP‑compatible client, such as Claude Desktop.
Details
- License
- MIT
Explore
- Query and control Home Assistant entities via natural language
- Works with any MCP-compatible client (like Claude Desktop)
- Provides tools for state management, service calls, history, and more
- Secure authentication using Home Assistant long-lived access tokens
- Multiple transport options (stdio for local processes, SSE for remote clients)
- Demo mode with mock data for testing and demonstration when Home Assistant is not available
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Home Assistant MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
bun install -g home-assistant-mcp-server
git clone https://github.com/oleander/home-assistant-mcp-server.git
cd home-assistant-mcp-server
bun install
bun run build
bun link
HASS_URL=http://your-home-assistant:8123 # URL to your Home Assistant instance
HASS_TOKEN=your_long_lived_access_token # Long-lived access token for authentication
PORT=3000 # Port for the HTTP server (default: 3000)
HASS_MOCK=false # Enable mock data mode when Home Assistant is unavailable (default: false)
| Variable | Required | Default | Description |
| ------------ | -------- | ------- | ------------------------------------------------------------------------------------------ |
| HASS_URL | Yes | - | URL to your Home Assistant instance (e.g., http://homeassistant.local:8123) |
| HASS_TOKEN | Yes | - | Long-lived access token for authenticating with Home Assistant |
| PORT | No | 3000 | Port number for the HTTP server when using HTTP/SSE transport |
| HASS_MOCK | No | false | When set to "true", enables mock data mode for testing without a Home Assistant connection |
To get a long-lived access token:
1. Log in to your Home Assistant instance
2. Click on your profile (bottom left)
3. Scroll down to "Long-Lived Access Tokens"
4. Create a new token with a descriptive name
5. Copy the token value (you won't see it again)
home-assistant-mcp-server # Start with HTTP/SSE transport
home-assistant-mcp-server --stdio # Start with stdio transport for direct process communication
states
Query entity states
lights
List lights
light
Control a light
service
Call Home Assistant services
history
Retrieve historical entity data
services
List available services
config
Get Home Assistant configuration
domains
List available domains
error_log
Get Home Assistant error log
devices
Get all devices in Home Assistant
The server exposes several tools for interacting with Home Assistant:
- states - Query entity states
- lights - List lights
- light - Control a light
- service - Call Home Assistant services
- history - Retrieve historical entity data
- services - List available services
- config - Get Home Assistant configuration
- domains - List available domains
- error_log - Get Home Assistant error log
- devices - Get all devices in Home Assistant
For detailed usage examples, see docs/hass-mcp.md.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"home assistant mcp server": {
"home-assistant-mcp-server": {
"command": "bun",
"args": [
"run",
"build"
]
}
}
}
}McpServers
{
"home-assistant-mcp-server": {
"command": "bun",
"args": [
"run",
"build"
]
}
}A Model Context Protocol (MCP) server for integrating with Home Assistant, allowing LLMs to control and query your smart home.
Features
- Query and control Home Assistant entities via natural language
- Works with any MCP-compatible client (like Claude Desktop)
- Provides tools for state management, service calls, history, and more
- Secure authentication using Home Assistant long-lived access tokens
- Multiple transport options (stdio for local processes, SSE for remote clients)
- Demo mode with mock data for testing and demonstration when Home Assistant is not available
Installation
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
