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 automation fire last night?"
• "List all unavailable or unknown entities"
• "Disable the orphaned sensor that no longer exists"
• "Show me the debug logs for the MQTT integration"
• "Search for entities related to my living room"

Available Tools

Hass-MCP-Plus provides 24 tools for interacting with Home Assistant:

Entity Management

• get_entity: Get the state of a specific entity with optional field filtering
• entity_action: Perform actions on entities (turn on, off, toggle) with domain-specific parameters
• list_entities: Get entities with domain filtering, search, and output format options (lean/compact/detailed)
• search_entities: Search for entities matching a query string across IDs, names, and attributes
• query_entities: Filter entities using CEL expressions with numeric comparisons and boolean logic
• domain_summary: Get a summary of a domain's entities with state distribution and examples
• system_overview: Get a comprehensive overview of the entire Home Assistant system

Entity Registry

• get_entity_registry: Get detailed registry entry for a single entity (platform, device, area, status)
• list_entity_registry: List all registry entries with optional domain filter (for auditing and bulk management)
• update_entity: Update entity properties — rename, change icon, assign area, disable/enable, hide/unhide
• remove_entity: Remove an entity from the registry (requires explicit confirm=True flag)

Automation & Debugging

• list_automations: Get all automations with pagination support
• list_automation_traces: Get recent execution traces for a specific automation
• get_automation_trace: Get detailed trace for a specific automation run (trigger, conditions, actions, errors)
• get_error_log: Get the Home Assistant error log with integration/level filtering
• get_core_logs: Get core journal logs (DEBUG/INFO/WARNING/ERROR) with integration/pattern filtering
• set_log_level: Set log level for any integration (enable debug logging, then read with get_core_logs)

Historical Data

• get_history: Get raw state change history with automatic pagination and sampling
• get_history_range: Get state changes for a specific date/time range with sampling strategies
• get_statistics: Get aggregated statistics (mean, min, max) with configurable periods (5min/hour/day/week/month)
• get_statistics_range: Get long-term statistics for any date range — the best tool for historical analysis

System

• get_version: Get the Home Assistant version
• call_service: Call any Home Assistant service (low-level API access)
• restart_ha: Restart Home Assistant

Development

Running Tests

uv run pytest tests/ -v

License

MIT License