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

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

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

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

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

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