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

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

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

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"

License

MIT License