Hass-MCP

Overview

• 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)

1. Pull the Docker image:

   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:

   {
     "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)

mcp add

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

YOUR_LONG_LIVED_TOKEN

Usage Examples

• "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

• 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

• 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://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

uv run pytest tests/

License