ha-mcp-guide

name	ha-mcp-guide
description	Use when working with Home Assistant via the ha-mcp MCP server. Examples: "create automation", "toggle light", "list entities in living room", "patch dashboard", "create helper", "query sensors".

ha-mcp Guide

Entry point for all ha-mcp work. Read this first, then follow the task-specific skill below.

When to Use

Whenever the user mentions HA entities, automations, scripts, scenes, helpers, dashboards, areas, devices, services, or anything related to Home Assistant.

Always Do

• Use format=natural for reads — LLM-optimized prose, 30-60% fewer tokens than JSON.
• Call manage_*:get before update or patch — list returns summary only, Config is not populated.
• Use manage_automation / manage_script / manage_scene for CRUD — never call_service for lifecycle.
• Smart Wait is server-side — after mutations the server polls and appends State changes: entity: old → new — do not poll manually.
• All IDs accept entity_id, config UUID, or friendly-name substring — use whichever you have.

Skills

Task	Skill
Which tool / action to use?	ha-mcp-tools
Unexpected error or behavior	ha-mcp-gotchas
Edit automation / script / scene / dashboard	ha-mcp-patching
Reduce tokens or batch operations	ha-mcp-efficiency

Tool Cheat Sheet

Entities

• query_entities — query all entities by state, domain, area, presence, health, history, statistics (modes: current/history/statistics/domains/presence/health)
• query_devices — device health check (disabled, orphaned, config errors)
• get_state — single entity state + attributes
• analyze_entity — entity usage in automations/scripts/scenes + registry metadata
• get_entity_dependencies — all entities an automation/script depends on

Registries

• get_registry — read entities/devices/areas registry in bulk
• manage_area — area CRUD + label/alias modes + include_entities/include_automations on get
• manage_entity — entity registry update/delete (rename, reassign area, labels, aliases)
• manage_device — device registry update/delete (labels, area, disable)
• manage_label / manage_floor / manage_zone / manage_person / manage_tag — registry CRUD
• manage_config_entry — list/get config entries (read-only)

Automations / Scripts / Scenes

• manage_automation — list/get/create/update/delete/toggle/coverage/patch
• manage_script — list/get/create/update/delete/execute/patch
• manage_scene — list/get/create/update/delete/activate/patch

Helpers

• manage_helper — lifecycle for all 26 helper types (list/create/update/delete/get_details)
• helper_action — runtime operations (toggle, set, increment, start, pause, cancel, …)

Services

• call_service — call any HA service (use for device control, not CRUD)
• list_services — browse available services with descriptions

Dashboards / Media / Camera

• manage_dashboard — dashboard CRUD + patch (match views/cards by title)
• browse_media / sign_media_path — media browsing + signed URLs
• manage_camera — snapshot (returns image) or stream (returns URL)

System / Admin

• get_system_info / get_datetime / validate_config / render_template
• get_logbook — logbook entries (mode: entries, correlation)
• manage_update — HA and add-on updates (list/release_notes/install/skip)
• manage_trace — automation/script execution traces (list/get/debug)
• manage_blueprint — blueprint list/import (public https:// URL required)
• manage_calendar / manage_todo / manage_hacs

Analysis

• analyze_target — capabilities of a target (triggers/conditions/services/entities/all)