Home Assistant MCP Server
by
Enable AI assistants to query and control Home Assistant entities, retrieve summaries, manage automations, and conduct guided conversations using lean JSON responses.
Home Assistant MCP Server Overview
What is Home Assistant MCP Server about?
Home Assistant MCP Server provides a set of tools that let large language models (LLMs) like Claude interact directly with a Home Assistant instance. The server exposes commands for reading entity states, performing actions, searching devices, summarizing domains, and managing automations, all through the Model Context Protocol (MCP).
How to use Home Assistant MCP Server?
- Prerequisites – A running Home Assistant instance and a long‑lived access token.
- Installation – Either run the Docker image
voska/hass-mcp:latestor install viauv(Python 3.13+). - Configuration – Add the MCP server to the LLM client (Claude Desktop, Cursor, Claude Code CLI) by specifying the command and the required environment variables
HA_URLandHA_TOKEN. - Interaction – Once the tool appears in the LLM’s tool menu, you can invoke the provided functions (e.g.,
get_entity,entity_action,list_automations) via natural‑language prompts.
Key features of Home Assistant MCP Server
- Entity Management – Get state, control, and search Home Assistant entities.
- Domain Summaries – High‑level overviews of lights, climate, sensors, etc.
- Automation Support – List, trigger, and create automations via guided prompts.
- Guided Conversations – Pre‑written prompts for common tasks like creating automations or troubleshooting.
- Smart Search – Query entities by name, type, or state.
- Token Efficiency – Minimal JSON payloads to keep LLM token usage low.
Use cases of Home Assistant MCP Server
- Voice‑like conversational control of smart home devices through an LLM.
- Automated troubleshooting of failing automations with step‑by‑step guidance.
- Generating routine‑optimizing suggestions based on actual usage patterns.
- Building custom dashboards by asking the model to lay out entities intelligently.
- Integrating Home Assistant into AI‑driven workflows (e.g., home‑energy reports, security alerts).
FAQ from the Home Assistant MCP Server
Q: How do I obtain a long‑lived token? A: In Home Assistant UI go to Profile → Long‑Lived Access Tokens and create a new token.
Q: Can I run the server without Docker?
A: Yes. With Python 3.13+ you can install the package using uv and run hass-mcp directly.
Q: What if Home Assistant is also running in Docker on the same host?
A: Add --network host to the Docker arguments or use the host’s IP address instead of host.docker.internal.
Q: Which LLM clients are supported? A: Claude Desktop, Cursor, Claude Code CLI, and any other MCP‑compatible client.
Q: How do I limit the size of search results?
A: Use the limit parameter in the hass://search/{query}/{limit} resource endpoint.
Home Assistant MCP Server's README
Hass-MCP
A Model Context Protocol (MCP) server for Home Assistant integration with Claude and other LLMs.
Overview
Hass-MCP enables AI assistants like Claude to interact directly with your Home Assistant instance, allowing them to:
- Query the state of devices and sensors
- Control lights, switches, and other entities
- Get summaries of your smart home
- Troubleshoot automations and entities
- Search for specific entities
- Create guided conversations for common tasks
Screenshots
Features
- Entity Management: Get states, control devices, and search for entities
- Domain Summaries: Get high-level information about entity types
- Automation Support: List and control automations
- Guided Conversations: Use prompts for common tasks like creating automations
- Smart Search: Find entities by name, type, or state
- Token Efficiency: Lean JSON responses to minimize token usage
Installation
Prerequisites
- Home Assistant instance with Long-Lived Access Token
- One of the following:
- Docker (recommended)
- Python 3.13+ and uv
Setting Up With Claude Desktop
Docker Installation (Recommended)
-
Pull the Docker image:
docker pull voska/hass-mcp:latest -
Add the MCP server to Claude Desktop:
a. Open Claude Desktop and go to Settings b. Navigate to Developer > Edit Config c. Add the following configuration to your
claude_desktop_config.jsonfile:{ "mcpServers": { "hass-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "HA_URL", "-e", "HA_TOKEN", "voska/hass-mcp" ], "env": { "HA_URL": "http://homeassistant.local:8123", "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN" } } } }d. Replace
YOUR_LONG_LIVED_TOKENwith your actual Home Assistant long-lived access token e. Update theHA_URL:- If running Home Assistant on the same machine: use
http://host.docker.internal:8123(Docker Desktop on Mac/Windows) - If running Home Assistant on another machine: use the actual IP or hostname
f. Save the file and restart Claude Desktop
- If running Home Assistant on the same machine: use
-
The "Hass-MCP" tool should now appear in your Claude Desktop tools menu
Note: If you're running Home Assistant in Docker on the same machine, you may need to add
--network hostto the Docker args for the container to access Home Assistant. Alternatively, use the IP address of your machine instead ofhost.docker.internal.
uv/uvx
-
Install uv on your system.
-
Add the MCP server to Claude Desktop:
a. Open Claude Desktop and go to Settings b. Navigate to Developer > Edit Config c. Add the following configuration to your
claude_desktop_config.jsonfile:{ "mcpServers": { "hass-mcp": { "command": "uvx", "args": ["hass-mcp"], "env": { "HA_URL": "http://homeassistant.local:8123", "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN" } } } }d. Replace
YOUR_LONG_LIVED_TOKENwith your actual Home Assistant long-lived access token e. Update theHA_URL:- If running Home Assistant on the same machine: use
http://host.docker.internal:8123(Docker Desktop on Mac/Windows) - If running Home Assistant on another machine: use the actual IP or hostname
f. Save the file and restart Claude Desktop
- If running Home Assistant on the same machine: use
-
The "Hass-MCP" tool should now appear in your Claude Desktop tools menu
Other MCP Clients
Cursor
- Go to Cursor Settings > MCP > Add New MCP Server
- Fill in the form:
- Name:
Hass-MCP - Type:
command - Command:
docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp - Replace
YOUR_LONG_LIVED_TOKENwith your actual Home Assistant token - Update the HA_URL to match your Home Assistant instance address
- Name:
- Click "Add" to save
Claude Code (CLI)
To use with Claude Code CLI, you can add the MCP server directly using the mcp add command:
Using Docker (recommended):
claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp
Replace YOUR_LONG_LIVED_TOKEN with your actual Home Assistant token and update the HA_URL to match your Home Assistant instance address.
Usage Examples
Here are some examples of prompts you can use with Claude once Hass-MCP is set up:
- "What's the current state of my living room lights?"
- "Turn off all the lights in the kitchen"
- "List all my sensors that contain temperature data"
- "Give me a summary of my climate entities"
- "Create an automation that turns on the lights at sunset"
- "Help me troubleshoot why my bedroom motion sensor automation isn't working"
- "Search for entities related to my living room"
Available Tools
Hass-MCP provides several tools for interacting with Home Assistant:
get_version: Get the Home Assistant versionget_entity: Get the state of a specific entity with optional field filteringentity_action: Perform actions on entities (turn on, off, toggle)list_entities: Get a list of entities with optional domain filtering and searchsearch_entities_tool: Search for entities matching a querydomain_summary_tool: Get a summary of a domain's entitieslist_automations: Get a list of all automationscall_service_tool: Call any Home Assistant servicerestart_ha: Restart Home Assistantget_history: Get the state history of an entityget_error_log: Get the Home Assistant error log
Prompts for Guided Conversations
Hass-MCP includes several prompts for guided conversations:
create_automation: Guide for creating Home Assistant automations based on trigger typedebug_automation: Troubleshooting help for automations that aren't workingtroubleshoot_entity: Diagnose issues with entitiesroutine_optimizer: Analyze usage patterns and suggest optimized routines based on actual behaviorautomation_health_check: Review all automations, find conflicts, redundancies, or improvement opportunitiesentity_naming_consistency: Audit entity names and suggest standardization improvementsdashboard_layout_generator: Create optimized dashboards based on user preferences and usage patterns
Available Resources
Hass-MCP provides the following resource endpoints:
hass://entities/{entity_id}: Get the state of a specific entityhass://entities/{entity_id}/detailed: Get detailed information about an entity with all attributeshass://entities: List all Home Assistant entities grouped by domainhass://entities/domain/{domain}: Get a list of entities for a specific domainhass://search/{query}/{limit}: Search for entities matching a query with custom result limit
Development
Running Tests
uv run pytest tests/
License
Home Assistant MCP Server Reviews
Login Required
Please log in to share your review and rating for this MCP.
Actions
Home Assistant MCP Server's Information
- Author
- voska
- Category
- Workflow & Automation
- Language
- Python
- License
- MIT License
- Stars
- 161
- Updated
- 21 days ago
Configuration
{
"mcpServers": {
"hass-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"HA_URL",
"-e",
"HA_TOKEN",
"voska/hass-mcp"
],
"env": {
"HA_URL": "http://homeassistant.local:8123",
"HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
}
}
}
}Configure Clients
Similar MCP Servers like Home Assistant MCP Server
Explore related MCPs that share similar capabilities and solve comparable challenges
Skyvern
Officialby Skyvern-AI
Automates browser‑based workflows by leveraging large language models and computer‑vision techniques, turning natural‑language prompts into fully functional web interactions without writing custom scripts.
BlenderMCP
Officialby ahujasid
Enables Claude AI to control Blender for prompt‑assisted 3D modeling, scene creation, and manipulation via a socket‑based Model Context Protocol server.
Pipedream
by PipedreamHQ
Connect APIs quickly with a free, hosted integration platform that enables event‑driven automations across 1,000+ services and supports custom code in Node.js, Python, Go, or Bash.
Inbox Zero
by elie222
Organizes email inbox, drafts replies in the user's tone, tracks follow‑ups, and provides analytics to achieve inbox zero quickly.
Cursor Talk To Figma
by grab
Enables Cursor AI to read and programmatically modify Figma designs through a Model Context Protocol integration.
Ableton MCP
by ahujasid
Enables Claude AI to control Ableton Live in real time, allowing AI‑driven creation, editing, and playback of tracks, clips, instruments, and effects through a socket‑based server.
N8n Mcp Server
by leonardsellem
Provides tools and resources to enable AI assistants to manage and execute n8n workflows via natural language commands.
Gmail AutoAuth MCP Server
by GongRzhe
Provides a Model Context Protocol server that enables AI assistants to send, read, search, and organize Gmail messages, supporting attachments, label and filter management, and automatic OAuth2 authentication.
Flujo
Clientby mario-andreschak
A unified platform that manages AI models, MCP servers, and complex workflows, offering secure key storage, visual flow building, and an interactive chat UI.