Set Integration
ha_set_integrationManage Home Assistant integration config entries: enable or disable, add via step-by-step config flows, update options, reconfigure connections, set log levels, and send integration commands.
Instructions
Manage an integration (config entry): enable/disable, add, update options, reconfigure, or send its own commands.
Modes (pick one):
Enable/disable: entry_id + enabled.
Add integration: domain (+ menu_choice, + config) — runs the domain's config flow one step per call, as the HA UI does.
Update options: entry_id (+ menu_choice, + config) — the entry's options flow (what the "Configure" button does in the HA UI), one step per call.
Reconfigure: entry_id + reconfigure=True — connection settings such as host, port, credentials, one step per call. Each call except an abort first checks the entry's identity; the first call without config returns the flow's first step.
Log level: log_level + domain (or entry_id) — sets how much the integration logs; read it back with ha_get_integration's log_level.
Integration command: entry_id + ws_command (+ ws_data) — what the integration's panel sends (KNX project, entities, telegrams). Home Assistant marks none of these commands as read-only, so a read such as knx/get_knx_project goes through this tool too.
Flows, one step per call: a call answers the step the flow is at and returns Home Assistant's next answer. A form comes back with its fields (type, default, current value, Home Assistant's help text) and flow_id; a menu with menu_options. Answer with flow_id and config (a form) or menu_choice (a menu); flow_id alone returns the step again, and flow_id with abort=True ends the flow. Without flow_id a new flow starts: its first form gets config, and without config the call returns that first step. A form Home Assistant rejects is an error with errors and error_text (Core's text), and the flow stays open to correct it. A flow stays open until Home Assistant finishes it or you abort it; while a setup flow is open, Home Assistant refuses another one for the same device as already_in_progress.
WHEN NOT TO USE:
Helpers (template, group, utility_meter, ...): use ha_config_set_helper.
otpis the user's to set up in the HA UI: its secret is a credential enrolled in an authenticator app; do not create it.Config subentries: use ha_config_set_helper(helper_type='config_subentry'); subentry_type here describes their form; a menu_choice that finishes the flow saves the subentry.
Removing an entry: use ha_remove_helpers_integrations.
ha-mcp's own ha_mcp_tools entries are refused: manage them in the HA UI, or (server settings, developer mode on) ha_dev_manage_settings / ha_dev_manage_server.
Use ha_get_integration() to find entry IDs, and ha_get_integration(entry_id=..., include_schema=True) to inspect the options fields. Its supports_reconfigure field tells you whether an entry qualifies for reconfigure=True, and ha_get_integration(entry_id=..., include_ws_commands=True) lists the commands ws_command accepts with their schemas.
Caveats: adding an integration runs its config flow exactly as the HA UI would (may pair devices, scan the network, create entities). Flows requiring a browser step (OAuth) are refused at that step and aborted. A progress step (Home Assistant working in the background) is waited out for up to 120 s; after that the error carries flow_id to ask again. When Home Assistant does not answer a submit or a progress poll (or, on reconfigure, answers with any 5xx), the error carries status applied_but_unverified: the entry may exist or the change may be saved, so check it before retrying. An aborted flow returns Core's own text next to the key (reason_text). Reconfigure edits the settings a live integration connects with: a wrong host or credential takes it offline, and there is no automatic rollback. A finished reconfigure waits for the reload Home Assistant runs and reports the entry's state as entry_state: status applied_and_verified once it is loaded, applied_but_unverified otherwise.
EXAMPLES:
Add: ha_set_integration(domain="local_calendar", config={"calendar_name": "Chores"})
Add in two steps: ha_set_integration(domain="knx", config={"connection_type": "routing"}) returns the routing form and flow_id, then ha_set_integration(domain="knx", flow_id="...", config={})
Answer a menu: ha_set_integration(domain="...", flow_id="...", menu_choice="")
See the setup form first: ha_set_integration(domain="workday")
Update options: ha_set_integration(entry_id="abc123", config={"scan_interval": 30})
Reconfigure: ha_set_integration(entry_id="abc123", reconfigure=True), then ha_set_integration(entry_id="abc123", reconfigure=True, flow_id="...", config={"host": "10.0.0.5"})
Cancel a flow: ha_set_integration(domain="knx", flow_id="...", abort=True)
Debug logging: ha_set_integration(domain="zha", log_level="DEBUG"), then log_level="DEFAULT" to stop
KNX project: ha_set_integration(entry_id="abc123", ws_command="knx/get_knx_project")
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.
integration config entry enable disable add options reconfigure log level debug logging
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "ha_set_integration"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| abort | No | With flow_id: end the open flow without saving. A flow Home Assistant no longer has, or one ha-mcp did not open (or opened before it restarted), is an error. | |
| config | No | The values for the form the flow is at: one form per call. Without flow_id it answers the new flow's first form (after menu_choice, when the flow opens with a menu). A key the form does not declare is refused before anything is sent. On an existing entry (options, reconfigure) a field you omit keeps its current value, and a field set to null is cleared where the integration's schema allows that field to be empty. | |
| domain | No | Integration domain to add (e.g. 'workday', 'local_calendar'). | |
| enabled | No | True to enable, False to disable the entry. Mutually exclusive with 'domain' and 'config'. | |
| flow_id | No | Continue an open flow: the flow_id a previous call returned, with the same domain or entry_id (and reconfigure=True for a reconfigure flow), until ha-mcp restarts. With config or menu_choice it answers the step; alone it returns the step again. | |
| ws_data | No | The ws_command's arguments, without 'type' and 'id'. Home Assistant checks them against the command's registered schema and returns its error when they do not match. | |
| entry_id | No | Config entry ID of an existing integration. | |
| log_level | No | Set the integration's log level, like the integration page's Enable/Disable debug logging: pass the integration with 'domain' (no config flow runs) or 'entry_id', and no other mode's parameters (log_persistence may accompany it). Lasts through the next Home Assistant restart unless log_persistence says otherwise. DEFAULT clears the override: the integration then logs at the inherited default level, and a level set for it in configuration.yaml returns only after a restart. | |
| ws_command | No | With entry_id: one of the integration's own '<domain>/' WebSocket commands to send, as its panel in the HA UI does (e.g. 'knx/get_knx_project'). Its result is returned under result. Streaming commands are refused. | |
| menu_choice | No | The option to pick at a menu step: with flow_id the menu the flow is at, without it the menu a new flow opens with. Refused when the step is not a menu or does not offer the option. | |
| reconfigure | No | Use the existing config entry's official reconfigure flow (its connection settings) instead of its options flow. Every call except an abort checks the entry's identity first. Without flow_id and config this opens the flow and returns its first step; nothing is submitted. Continue with the flow_id this entry's call returned: Home Assistant does not say which entry a reconfigure flow edits. | |
| subentry_id | No | With entry_id and subentry_type: the existing subentry whose reconfigure form to describe. | |
| expected_mac | No | Requires reconfigure=True. MAC or IEEE the entry's device must still report. | |
| subentry_type | No | With entry_id: the integration-defined subentry type whose form to describe as subentry_schema; the flow is aborted afterwards, unless a menu_choice finished it (flow_type create_entry: saved). | |
| log_persistence | No | Only with log_level: how long Home Assistant keeps the level. 'once' (default) through the next restart, 'permanent' after every restart until changed, 'none' until the next restart. Home Assistant validates the value. | |
| expected_device_id | No | Requires reconfigure=True. Device registry ID the entry must still own. | |
| expected_unique_id | No | Requires reconfigure=True, AND the ha_mcp_tools custom component: Home Assistant does not expose a config entry's unique_id over its API. Without the component this is rejected — anchor on expected_device_id, expected_mac or expected_entity_ids instead. | |
| expected_entity_ids | No | Requires reconfigure=True. Exact entity IDs that must remain associated with the entry. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||