Skip to main content
Glama
homeassistant-ai

Home Assistant MCP Server

Official
by homeassistant-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Manage Blueprints

ha_manage_blueprints
Destructive

Manage the full Home Assistant blueprint lifecycle: list, read, import, save, delete, or render a blueprint into a standalone automation or script config.

Instructions

Manage Home Assistant blueprints — list, read, import, save, delete, or render a standalone config.

One interface for the whole blueprint lifecycle in the automation and script domains.

DO NOT use this to create an automation or script FROM a blueprint — that is ha_config_set_automation / ha_config_set_script with a use_blueprint config.

To duplicate a blueprint, get it and save its yaml under a new path; to edit one in place, get it, change the text, and save it back to the same path with overwrite=True.

get also reports used_by: the automations or scripts built on the blueprint, which is the UI's "Show automations using this blueprint". Check it before deleting — Home Assistant refuses to delete a blueprint anything still uses (the error lists the consumers), and it goes on counting a consumer that has since taken control of its own config until that consumer is removed.

CAVEATS: get returns the on-disk YAML only when something can read it — an in-process server, the ha_mcp_tools component, the File & YAML Tools entry, or the blueprint's source_url; yaml_source names which one answered, and source_url text is a fresh download that can differ from the installed file. Core's blueprint API alone exposes metadata only, so a locally authored blueprint on a bare install has no readable text. Both writes are snapshotted first when a copy can be read, so ha_manage_backup(scope="edits") can restore the previous file. substitute only renders — it writes nothing, so pass the returned config to ha_config_set_automation / ha_config_set_script to persist it. To convert an automation or script that ALREADY exists, prefer those tools' take_control_of_blueprint=True: it renders with that item's own current inputs and saves the result over itself in one call.

EXAMPLES:

  • Get one (with its consumers in used_by): ha_manage_blueprints(action="get", path="homeassistant/motion_light.yaml")

  • Import: ha_manage_blueprints(action="import", url="https://example.com/bp.yaml")

  • Edit in place: ha_manage_blueprints(action="save", path="user/motion.yaml", yaml=, overwrite=True)

  • Delete: ha_manage_blueprints(action="delete", path="user/motion.yaml", confirm=True)

  • Render standalone: ha_manage_blueprints(action="substitute", path="user/motion.yaml", input={"motion_sensor": "binary_sensor.hall"})

RELATED TOOLS: ha_config_remove_automation / ha_config_remove_script to clear consumers blocking a delete, ha_search to find them.

If a Claude Desktop user gets a 4-minute timeout with no result on this call, read the target back before repeating it, and tell them to wait a few seconds before clicking the manual-approve button, as clicking it too quickly is known to cause hangs in Claude Desktop. This workaround is specific to Claude Desktop.

blueprint blueprints import delete remove unused substitute take-control list ha_get_blueprint ha_import_blueprint

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlNoURL to import from — GitHub, Home Assistant Community, or a direct YAML link (action='import')
pathNoInstalled blueprint path, e.g. 'homeassistant/motion_light.yaml' (action='get' / 'save' / 'delete' / 'substitute'). 'save' appends '.yaml' when it is missing, as Home Assistant does.
yamlNoBlueprint YAML text to write (action='save')
inputNoBlueprint input values keyed by input name (action='substitute'); defaults to {}
actionYes'list' installed blueprints, 'get' one blueprint's metadata/inputs/YAML, 'import' one from a URL, 'save' YAML text to a blueprint path, 'delete' an installed one, or 'substitute' to render a standalone config (the UI's "Take control")
domainNoBlueprint domain: 'automation' or 'script'. Ignored by action='import' — the blueprint file declares its own domain.automation
confirmNoRequired confirmation for action='delete'
overwriteNoWrite over an already-installed blueprint (action='import' / 'save'). Home Assistant reloads every automation/script using it.
source_urlNoOrigin URL to stamp into the saved blueprint's metadata (action='save'); omit for a hand-authored blueprint

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv8.6.0
    • changedInput schema / properties / action / description
      Previous value: -"'list' installed blueprints, 'get' one blueprint's metadata/inputs/YAML, 'import' one from a URL, 'save' YAML text to a blueprint path, 'delete' an installed one, or 'substitute' to render a standalone config"New value: +"'list' installed blueprints, 'get' one blueprint's metadata/inputs/YAML, 'import' one from a URL, 'save' YAML text to a blueprint path, 'delete' an installed one, or 'substitute' to render a standalone config (the UI's \"Take control\")"
  2. Addedv8.5.0

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false and readOnlyHint=false, so the risk profile is covered. The description nonetheless adds genuinely useful behavior the annotations cannot: get may return no YAML on a bare install, yaml_source identifies the reader, source_url is a fresh download, both writes are snapshotted for backup, substitute writes nothing, and HA refuses to delete an in-use blueprint. This is above the annotation baseline but stops short of the richness expected at 5 given how much it already front-loads.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the lifecycle summary and the key exclusion, then caveats and worked examples. Dense but largely earns its length. The trailing Claude Desktop timeout workaround is operational trivia that dilutes an otherwise well-structured description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nine-parameter, six-action tool with an output schema and annotations present, the description covers lifecycle routing, caveats about unreadable YAML, backup interaction, and cross-tool handoffs. Nothing an agent needs in order to choose an action correctly appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description still adds cross-parameter semantics the schema cannot express: get→save with a new path duplicates, same path with overwrite=True edits in place, and substitute's output must be handed to ha_config_set_automation/script to persist. These pairings of action+parameter are meaningful beyond the per-parameter schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Explicitly names the resource (Home Assistant blueprints) and enumerates the six operations (list, read, import, save, delete, render). It also carves the boundary against the most confusable siblings by stating this is not the tool that creates automations/scripts FROM a blueprint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-not guidance ('DO NOT use this to create an automation or script FROM a blueprint' → names ha_config_set_automation / ha_config_set_script) plus concrete workflows for duplication and in-place edits, and a pre-delete check via used_by. Alternatives (take_control_of_blueprint=True for existing items) are named with their selection condition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools