A Model Context Protocol server that enables AI assistants to directly interact with Home Assistant instances, providing the ability to query device states, manage entities, control automations, and troubleshoot smart home systems.

Installation

Docker

docker pull voska/hass-mcp:latest

uvx

uvx hass-mcp

Configuration

Claude Desktop (Docker)

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

Claude Desktop (uvx)

{
  "mcpServers": {
    "hass-mcp": {
      "command": "uvx",
      "args": ["hass-mcp"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
      }
    }
  }
}

Available Tools

Tool	Description
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, turn off, toggle)
list_entities	Get a list of entities with optional domain filtering and search
search_entities_tool	Find entities matching a query
domain_summary_tool	Get a summary of entities in a domain
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

Capabilities

• Query device and sensor states
• Control lights, switches, and other entities
• Get summaries of your smart home
• Troubleshoot automations and entities
• Search for specific entities
• Create guided dialogs for common tasks
• Manage entities with states and controls
• Domain summaries for high-level information
• Automation support for listing and management
• Intelligent search to find entities by name, type, or state

Environment Variables

Required

• HA_URL - The URL of your Home Assistant instance
• HA_TOKEN - Home Assistant long-lived access token

Usage Examples

What is the current state of the living room light?

Turn off all the lights in the kitchen

Show me all my sensors that contain temperature data

Give me a summary of my climate entities

Create an automation that turns on the light at sunset

Notes

Includes guided dialog prompts for creating automations, debugging, troubleshooting entities, optimizing routines, checking automation status, ensuring consistent entity naming, and generating dashboard layouts. Provides resource endpoints for direct entity access and search capabilities.