home / mcp / hass mcp server

Hass MCP Server

Home Assistant MCP Server

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "voska-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"
      }
    }
  }
}

You can run Hass-MCP as a local MCP server that lets Claude and other LLMs interact with your Home Assistant instance. It exposes Home Assistant data and actions through a lean, token-efficient interface, enabling you to query device states, control entities, explore automations, and troubleshoot your smart home workflows from your AI assistant.

How to use

Use Hass-MCP with an MCP client to perform common Home Assistant tasks through natural prompts. You can ask it to check the current state of devices, turn lights on or off, search for entities by name or domain, list automations, or create guided conversations for automations. The responses are designed to be concise to save tokens while still giving you the information you need.

How to install

Prerequisites you need before starting:

A Home Assistant instance with a Long-Lived Access Token
Docker (recommended) or Python 3.13+ with uv

Choose one setup path and follow the steps below.

docker pull voska/hass-mcp:latest

Docker/Claude Desktop setup (recommended)

Configure Hass-MCP as a stdio MCP server via Docker and connect it to Claude Desktop. The following configuration runs the MCP server container and exposes the required environment variables.

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

uv/uvx setup

Install uv on your system and run Hass-MCP through uvx. This path is lightweight and suitable for local development or minimal deployments.

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

Additional notes on setup or troubleshooting

If you run Home Assistant on a different machine, update the HA_URL to point to that machine’s address. Ensure the long-lived access token has the necessary permissions for the actions you intend to perform.

Examples of common tasks

Ask Hass-MCP to describe the current state of your living room lights, list all temperature sensors, or create a simple automation to turn on lights at sunset. Use concise prompts to get targeted results and minimize token usage.

Security considerations

Treat your Home Assistant token like a secret key. Keep it in a secure environment variable and restrict access to the MCP client, especially when using shared workstations or cloud-based tooling.

Available tools

get_version

Retrieve the Home Assistant version currently running in your instance.

get_entity

Fetch the state of a specific entity with optional attribute filtering.

entity_action

Perform actions on entities, such as turning them on, off, or toggling their state.

list_entities

List entities with optional domain filtering and search terms.

search_entities_tool

Search for entities matching a query across domains.

domain_summary_tool

Provide a high-level summary of entities within a domain.

list_automations

List all automations in your Home Assistant setup.

call_service_tool

Call a Home Assistant service with parameters.

restart_ha

Restart Home Assistant.

get_history

Retrieve the state history for an entity.

get_error_log

Get the Home Assistant error log.