Hass-MCP
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Integrations
Offers deployment through Docker containers, making it easy to run the MCP server with proper environment configuration.
Enables querying and controlling Home Assistant entities (lights, switches, sensors), retrieving summaries of smart home devices, troubleshooting automations, searching for entities, and guiding through automation creation.
Supports native Python installation as an alternative to Docker deployment, with specific requirements for Python 3.13+ and uv.
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:
- 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.json
file:d. ReplaceYOUR_LONG_LIVED_TOKEN
with 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 host
to the Docker args for the container to access Home Assistant. Alternatively, use the IP address of your machine instead ofhost.docker.internal
.
Other MCP Clients
Cursor
- Go to Cursor Settings > MCP > Add New MCP Server
- Fill in the form:
- Name:
Hass-MCP
- Type:
command
- Command:
- Replace
YOUR_LONG_LIVED_TOKEN
with 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):
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
License
This server cannot be installed
A Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.
- Overview
- Screenshots
- Features
- Installation
- Setting Up With Claude Desktop
- Other MCP Clients
- Usage Examples
- Available Tools
- Prompts for Guided Conversations
- Available Resources
- Development
- License