home-assistant-mcp-server
概览
A Model Context Protocol (MCP) server for integrating with Home Assistant, allowing LLMs to control and query your smart home. - 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 Create a .env file in your current directory with the following variables: 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) 1. Edit your Claude Desktop config file: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.
README
以下为原文 README 节选，完整内容请查看原文。
Home Assistant MCP Server
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
# Install globally using bun
bun install -g home-assistant-mcp-server
# Or install from source
git clone https://github.com/oleander/home-assistant-mcp-server.git
cd home-assistant-mcp-server
bun install
bun run build
bun link
Configuration
Create a .env file in your current directory with the following variables:
# Required configurations
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
# Optional configurations
PORT=3000 # Port for the HTTP server (default: 3000)
HASS_MOCK=false # Enable mock data mode when Home Assistant is unavailable (default: false)
Environment Variables
| 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:
- Log in to your Home Assistant instance
- Click on your profile (bottom left)
- Scroll down to “Long-Lived Access Tokens”
- Create a new token with a descriptive name
- Copy the token value (you won’t see it again)
Usage
Running as a standalone server
# Standard mode (requires a running Home Assistant instance)
home-assistant-mcp-server # Start with HTTP/SSE transport
home-assistant-mcp-server --stdio # Start with stdio transport for direct process communication
# Demo mode (with mock data when Home Assistant is unavailable)
home-assistant-mcp-server --mock # Start with HTTP/SSE transport and mock data安装
This server does not publish a one-line install command.
Open the repository installation guide 新手？先看 mcpskill.org 教程 →配置
{
"mcpServers": {
"homeassistant": {
"command": "home-assistant-mcp-server"
"env": {
"HASS_URL": "http://your-home-assistant:8123",
"HASS_TOKEN": "your_token_here",
"HASS_MOCK": "true"
}
}
}
}