# 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](https://github.com/astral-sh/uv) ## Setting Up With Claude Desktop ### Docker Installation (Recommended) 1. Pull the Docker image: \`\`\`bash docker pull voska/hass-mcp:latest \`\`\` 2. 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: \`\`\`json \{ "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_TOKEN\` with your actual Home Assistant long-lived access token e. Update the \`HA_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 3. 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 of \`host.docker.internal\`. ## Other MCP Clients ### Cursor 1. Go to Cursor Settings > MCP > Add New MCP Server 2. 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_TOKEN\` with your actual Home Assistant token - Update the HA_URL to match your Home Assistant instance address 3. 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):** \`\`\`bash 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 version - \`get_entity\`: Get the state of a specific entity with optional field filtering - \`entity_action\`: Perform actions on entities (turn on, off, toggle) - \`list_entities\`: Get a list of entities with optional domain filtering and search - \`search_entities_tool\`: Search for entities matching a query - \`domain_summary_tool\`: Get a summary of a domain's entities - \`list_automations\`: Get a list of all automations - \`call_service_tool\`: Call any Home Assistant service - \`restart_ha\`: Restart Home Assistant - \`get_history\`: Get the state history of an entity - \`get_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 type - \`debug_automation\`: Troubleshooting help for automations that aren't working - \`troubleshoot_entity\`: Diagnose issues with entities - \`routine_optimizer\`: Analyze usage patterns and suggest optimized routines based on actual behavior - \`automation_health_check\`: Review all automations, find conflicts, redundancies, or improvement opportunities - \`entity_naming_consistency\`: Audit entity names and suggest standardization improvements - \`dashboard_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 entity - \`hass://entities/\{entity_id\}/detailed\`: Get detailed information about an entity with all attributes - \`hass://entities\`: List all Home Assistant entities grouped by domain - \`hass://entities/domain/\{domain\}\`: Get a list of entities for a specific domain - \`hass://search/\{query\}/\{limit\}\`: Search for entities matching a query with custom result limit ## Development ### Running Tests \`\`\`bash uv run pytest tests/ \`\`\` ## License [MIT License](LICENSE)