Hass-MCP-Plus MCP Server

Hass-MCP-Plus

A complete rewrite of voska/hass-mcp — an MCP server for Home Assistant built for token efficiency, security hardening, and context flooding prevention. Thanks to Matt Voska for the original project.

Features:

• 24 tools covering entity control, registry management, statistics, logs, and automation debugging
• CEL expression filtering for complex entity queries (e.g., "all battery sensors below 20%")
• Entity registry management with safe two-phase delete
• Long-term statistics with hourly/daily/weekly/monthly aggregation and date range support
• Core journal log access with debug-level and integration filtering
• Automation trace inspection for debugging failed runs
• Configurable output formats (lean/compact/detailed)
• Input validation, error sanitization, and context flooding prevention across all calls
• Works with Claude Desktop, Claude Code, Cursor, and other MCP clients

Installation

Prerequisites

• Home Assistant instance with a Long-Lived Access Token
• One of the following:
  • Docker (recommended)
  • Python 3.13+ and uv

Environment Variables

Variable	Required	Description
HA_URL	Yes	Home Assistant URL (e.g., http://192.168.1.100:8123)
HA_TOKEN	Yes	Home Assistant Long-Lived Access Token
HA_VERIFY_SSL	No	Set to true to enable SSL certificate verification (default: false). Useful when using HTTPS with self-signed certificates.
TZ	No	Timezone (e.g., America/Los_Angeles)

Docker (Recommended)

docker pull rmaher001/hass-mcp-plus:latest

Verify the server starts correctly:

docker run -i --rm \
  -e HA_URL=http://homeassistant.local:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  rmaher001/hass-mcp-plus

Note: If Home Assistant is running on the same machine, use http://host.docker.internal:8123 (Docker Desktop on Mac/Windows) or add --network host and use http://localhost:8123.

Python (uv/uvx)

pip install hass-mcp-plus

Run the server:

HA_URL=http://homeassistant.local:8123 HA_TOKEN=YOUR_LONG_LIVED_TOKEN uvx hass-mcp-plus

Client Configuration

<details> <summary><strong>Claude Code (CLI)</strong></summary>

claude mcp add hass-mcp-plus \
  -e HA_URL=http://homeassistant.local:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  -- docker run -i --rm -e HA_URL -e HA_TOKEN rmaher001/hass-mcp-plus

Replace YOUR_LONG_LIVED_TOKEN with your actual token and update HA_URL.

</details> <details> <summary><strong>Claude Desktop</strong></summary>

1. Open Claude Desktop → Settings → Developer → Edit Config
2. Add to claude_desktop_config.json:

Using Docker:

{
  "mcpServers": {
    "hass-mcp-plus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "rmaher001/hass-mcp-plus"
      ],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
      }
    }
  }
}

Using uvx:

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

3. Replace YOUR_LONG_LIVED_TOKEN with your actual token and update HA_URL to match your Home Assistant instance
4. Save and restart Claude Desktop

</details> <details> <summary><strong>Cursor</strong></summary>

1. Go to Cursor Settings → MCP → Add New MCP Server
2. Fill in the form:
   • Name: Hass-MCP-Plus
   • Type: command
   • Command:

     docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN rmaher001/hass-mcp-plus
     

3. Replace YOUR_LONG_LIVED_TOKEN with your actual token and update HA_URL
4. Click "Add" to save

</details>

Usage Examples

Here are some examples of prompts you can use with Claude once Hass-MCP-Plus is set up:

• "What's the current state of my living room lights?"
• "Turn off all the lights in the kitchen"
• "Find all battery sensors below 20%"
• "Give me a summary of my climate entities"
• "Show me the hourly temperature statistics for the last week"
• "Why didn't my motion sensor