菜单
Use when choosing which ha-mcp tool or action to call. Examples: "How do I list entities?", "create a helper", "turn on a light", "find devices in kitchen", "which action should I use?".
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use when editing an existing automation, script, scene, or dashboard with `action: patch`. Examples: "add a trigger", "replace a dashboard card", "remove a condition", "change automation mode", "add delay to trigger".
Use when a ha-mcp call returns an unexpected result, error, or behaves differently than expected. Examples: "scene not appearing after create", "helper entity_id is wrong", "patch failing with missing config", "automation ID mismatch".
Use when planning multi-call ha-mcp workflows or when token usage matters. Examples: "query 50 entities", "batch-update labels", "reduce response size", "avoid unnecessary API calls".
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".
| name | ha-mcp-tools |
| description | Use when choosing which ha-mcp tool or action to call. Examples: "How do I list entities?", "create a helper", "turn on a light", "find devices in kitchen", "which action should I use?". |
| User intent | Tool + Action |
|---|---|
| Turn on / off / toggle a device | call_service (domain=light/switch, service=turn_on/turn_off/toggle) |
| Get a single entity's current state | get_state |
| List entities in an area / by domain / by state | query_entities mode=current |
| Find unavailable / stale / disabled entities | query_entities mode=health |
| Person / device tracker presence (home/away) | query_entities mode=presence |
| Historical state for a sensor over time | query_entities mode=history |
| Aggregated stats (min/max/mean) for a sensor | query_entities mode=statistics |
| Which entity domains exist in this HA instance? | query_entities mode=domains |
| Device health (orphaned / config errors) | query_devices mode=health |
| Where is entity X used? (automations, scripts) | analyze_entity — returns RFC 6901 paths to each reference location |
| Which entities does automation X depend on? | get_entity_dependencies |
| Create / edit / delete an automation | manage_automation action=create/update/delete |
| Toggle / enable / disable an automation | manage_automation action=toggle |
| See automation trigger/condition/service coverage | manage_automation action=coverage |
| Add/remove a trigger or condition (surgical edit) | manage_automation action=patch (semantic op) |
| Run a script | manage_script action=execute |
| Activate a scene | manage_scene action=activate |
| Create a helper (input, timer, counter, etc.) | manage_helper action=create |
| Set / toggle / start a helper value at runtime | helper_action |
| Rename an entity in the registry | manage_entity action=update (new_entity_id field) |
| Assign an entity to an area | manage_entity action=update (area_id field) |
| Add / remove labels on entity or device | manage_entity / manage_device action=update + label_mode |
| List / create / rename an area | manage_area action=list/create/update |
| Check what config entries exist for an integration | manage_config_entry action=list (domain filter) |
| Browse available services | list_services |
| Render a Jinja2 template | render_template |
| Get logbook entries / cause-effect correlation | get_logbook mode=entries/correlation |
| Check HA version / timezone | get_system_info |
| Validate configuration.yaml | validate_config |
| Manage a dashboard (create / edit / view) | manage_dashboard |
| Install / uninstall a HACS add-on | manage_hacs action=download/uninstall |
| View automation / script execution trace | manage_trace action=list/get |
| Import a blueprint | manage_blueprint action=import |
| Check for HA / add-on updates | manage_update action=list (pending_only=true) |
| Manage todo list items | manage_todo |
| Manage calendar events | manage_calendar |
| Read HA error/warning logs | manage_system_log action=list |
| Clear the HA system log buffer | manage_system_log action=clear |
| Get ha-mcp guidance on a topic | get_skill action=list / action=read skill= |
| Tool | Read Actions | Write Actions |
|---|---|---|
manage_automation | list, get, coverage | create, update, delete, toggle, patch |
manage_script | list, get | create, update, delete, execute, patch |
manage_scene | list, get | create, update, delete, activate, patch |
manage_helper | list, get_details | create, update, delete |
manage_dashboard | list, get | create, update, delete, patch |
manage_area | list, get | create, update, delete |
manage_entity | get | update, delete |
manage_device | get | update, delete |
manage_label | list, get | create, update, delete |
manage_floor | list, get | create, update, delete |
manage_zone | list, get | create, update, delete |
manage_person | list, get | create, update, delete |
manage_tag | list, get | create, update, delete |
manage_config_entry | list, get | (none — read-only) |
manage_hacs | info, list, get, releases, release_notes, critical | download, uninstall, add_repository, remove_repository, refresh, toggle_beta |
manage_trace | list, get, debug | (none — read-only) |
manage_blueprint | list | import |
manage_update | list, release_notes | install, skip |
manage_todo | list, get_items | add_item, update_item, remove_item |
manage_calendar | list, get_events | create_event, delete_event |
manage_system_log | list | clear |
get_skill | list, read | (none — read-only) |
query_entities | current, history, statistics, domains, presence, health | (none) |
query_devices | health | (none) |
analyze_target | all, triggers, conditions, services, entities | (none) |
get_logbook | entries, correlation | (none) |
helper_action | (contextual) | toggle, set, increment, decrement, reset, calibrate, start, pause, cancel, finish, change, press, select, set_options, reload, add_entities, remove_entities |
Key non-obvious parameters for create and update actions:
manage_automation:
single | restart | queued | parallel (HA default: single)manage_script:
single | restart | queued | parallel (HA default: single)Access control filter syntax (for HA_MCP_TOOL_FILTER_WHITELIST / _BLACKLIST):
"manage_automation" — blocks/allows entire tool"manage_automation:create" — specific action"manage_*:delete" — glob across all manage_ tools"*:write" — all write operations (see Write Actions column above)read_only: true is shorthand for blacklisting *:write. Whitelist and blacklist are mutually exclusive.
| Mode | Use when |
|---|---|
current | Browse entities by domain/area/state — general listing |
history | Sensor/entity state over time (requires time range) |
statistics | Aggregated stats (min/max/mean) for sensor entities |
domains | Discover which entity domains exist in this HA instance |
presence | Person/device tracker home/away status |
health | Find unavailable, unknown, disabled, orphaned, or stale entities |
| Instead of… | Do this |
|---|---|
call_service to create/update/delete an automation | manage_automation action=create/update/delete |
Multiple get_state calls for a set of entities | query_entities mode=current with domain/area filter |
Patching after a list response | Call get first — list does not populate Config |
D:\data\godev\ha-mcp\docs\tools.md, internal/handlers/register.go, internal/mcp/access_control.go