Home Assistant MCP — Use Cases, Install & Live Demo

Why use it

Key features

Fuzzy entity search + deep config search across thousands of entities
Author and edit automations, scripts, scenes, helpers in YAML
Dashboard editor: create cards, layouts, views
History + statistics queries with chart-ready output
Energy dashboard, camera snapshots, automation traces

Live Demo

What it looks like in practice

ha-mcp.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "ha-mcp",
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "ha-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "ha-mcp"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add ha-mcp -- uvx ha-mcp

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Home Assistant MCP

Control devices without remembering entity IDs

👤 Anyone with a populated Home Assistant install ⏱ ~5 min beginner

When to use: You know what you want ("dim the kitchen to 30%") but not the exact entity_id.

Prerequisites

Home Assistant Long-Lived Access Token — Profile → Security → Create Token; save as HA_TOKEN env var
HA_URL set — Set HA_URL=http://homeassistant.local:8123 (or your URL)

Flow

Find the entity

Use ha-mcp. Find entities matching 'kitchen light'. Show entity_id, area, and current state.✓ Copied

→ 1–3 candidate entities with current state
Apply change

Set kitchen ceiling lights to 30% brightness, warm white.✓ Copied

→ Service call succeeds; state confirmed

Outcome: Devices controlled by intent, not memorization.

Pitfalls

Multiple entities match — wrong one toggled — Always confirm entity_id list before bulk action; use area filters

Author a complex automation from a plain-English spec

👤 HA users who avoid YAML ⏱ ~15 min intermediate

When to use: You want "if I leave home and it's after sunset and the cat feeder is empty, send me a notification" — and you don't want to write YAML.

Flow

Describe intent

Use ha-mcp. List my person tracker, sun, and cat feeder entities so we can wire an automation.✓ Copied

→ Relevant entities with state schema
Generate YAML

Create automation 'cat-feeder-sundown-alert' with that logic. Don't deploy yet — show me the YAML.✓ Copied

→ Valid HA automation YAML in chat
Deploy + trace

Deploy it. Then trigger it manually and show the trace so I can verify the conditions fired.✓ Copied

→ Automation in UI; trace shows expected branches

Outcome: Working automation, no /config/automations.yaml hand-editing.

Pitfalls

Automation deployed but never triggers — entity name typo — Use trace tool; verify entity_id matches exactly

Investigate an energy spike using history + statistics

👤 Smart-home owners with HA Energy dashboard ⏱ ~25 min intermediate

When to use: Your bill jumped and you want to know what changed.

Flow

Pull totals

Use ha-mcp. Compare total kWh per circuit for last 30 days vs the prior 30. Flag deltas >20%.✓ Copied

→ Per-circuit table with deltas highlighted
Drill into the worst

For the worst-offending circuit, plot hourly usage for the last 7 days and identify the new pattern.✓ Copied

→ Hourly profile + verbal observation of anomaly
Find the culprit device

Which entity on that circuit changed behavior? Cross-reference automations that touch it.✓ Copied

→ Specific device + automation pinpointed

Outcome: Concrete "the EV charger ran a new schedule" answer, not vague suspicion.

Pitfalls

Stats only as good as your sensor coverage — Acknowledge gaps; suggest where to add monitoring

Set up a 'vacation mode' that touches lights, locks, blinds, and notifications

👤 About to leave for a trip ⏱ ~30 min intermediate

When to use: You're leaving in an hour and want presence simulation + away-mode behavior.

Flow

Inventory affected entities

Use ha-mcp. List lights in living areas, all door locks, all blinds. Note which are HA-controllable.✓ Copied

→ Categorized entity list with controllability flag
Build the script

Create a script 'vacation_mode_on' that arms locks, randomizes evening lights 18:30–22:30, sets blinds to 50%, and pauses cleaning automations.✓ Copied

→ Script in HA; manual run succeeds
Add a trigger

Bind it to an input_boolean 'vacation_mode' so I can toggle from the dashboard.✓ Copied

→ Toggle on dashboard; flipping it runs the script

Outcome: One-click vacation mode; you leave with the dashboard armed.

Pitfalls

Auto-locking locks with people inside — Add a person presence check; never lock when someone's home

Combinations

Pair with other MCPs for X10 leverage

ha-mcp + filesystem

Back up automations.yaml + scripts.yaml to git

Export all automations and scripts via ha-mcp, write to ./ha-config/, commit.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
search_entities	query: str, area?, domain?	First step in almost every flow — find the entity_id	1 HA API call
call_service	domain, service, target, data	Apply any device or scene change	1 API call
create_automation	yaml_or_object	Programmatically author automations	1 API call
get_history	entity_id, start, end	Pull state history for analysis	1 API call
get_statistics	statistic_id, period (5min\|hour\|day\|month)	Long-term aggregate data (energy, climate)	1 API call
trace_automation	automation_id, run_id?	Debug why an automation did or didn't fire	1 API call

Cost & Limits

What this costs to run

API quota: No hard quota — REST API is local
Tokens per call: Variable; entity registry can be huge if you don't filter
Monetary: Free (open source)
Tip: Always use search_entities with filters — full registry dumps are expensive in tokens

Security

Permissions, secrets, blast radius

Minimum scopes: Long-Lived Access Token (full HA scope)

Credential storage: HA_TOKEN env var

Data egress: Only to your HA instance URL — keep on local network ideally

Never grant: HA token to any cloud LLM you don't trust — this controls physical access (locks, garage)

Long-lived tokens don't auto-rotate — rotate manually if you suspect leak
Test automations and locks in a way that doesn't lock you out (have a backup)

Troubleshooting

Common errors and fixes

Cannot connect to HA

Verify HA_URL is reachable from where the MCP runs; check trusted_proxies if behind a reverse proxy

Verify: curl $HA_URL/api/ -H 'Authorization: Bearer $HA_TOKEN'

401 Unauthorized

Token expired or revoked — generate new long-lived token in profile

Service call returns 400

Service signature mismatch — use the developer tools panel to verify the schema, then retry

Automation deployed but doesn't trigger

Use trace_automation to see which condition failed; common: entity_id typo or sun condition wrong timezone

Alternatives

Home Assistant MCP vs others

Alternative	When to use it instead	Tradeoff
Home Assistant native voice assistants (Piper/Whisper)	You want voice control without a cloud LLM in the path	Less natural language flexibility; more setup
ha-mcp-server (legacy/forks)	Your fork has features this one doesn't	Smaller surface; this one has 87 tools and active maintenance

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills