Skip to main content
Glama

Get Integration

ha_get_integration
Read-onlyIdempotent

Retrieve Home Assistant integration details: list and filter config entries or fetch one entry's options, schemas, diagnostics, and subentries for inspection and troubleshooting.

Instructions

Get integration (config entry) information with pagination.

Without an entry_id: Lists all configured integrations with optional filters. With an entry_id: Returns detailed information including full options/configuration.

WHEN NOT TO USE:

  • Changing an entry, or describing a setup form or a form behind a menu: use ha_set_integration (without config it returns the form).

EXAMPLES:

  • List / search: ha_get_integration(query="zigbee")

  • Get an entry with its editable fields: ha_get_integration(entry_id="abc123", include_schema=True)

  • Diagnostics dump, paged along a list-valued path: ha_get_integration(entry_id="abc123", include_diagnostics=True, diagnostics_data_path="", diagnostics_data_limit=10, diagnostics_data_offset=20)

  • Inspect a subentry reconfigure schema: ha_get_integration(entry_id="abc123", include_subentry_schema=True, subentry_type="conversation", subentry_id="sub123")

  • Options flow that opens with a menu: ha_get_integration(entry_id="abc123", include_schema=True) lists menu_options; ha_set_integration(entry_id="abc123", menu_choice="") opens that form

  • List template entries with their options: ha_get_integration(domain="template")

  • Only service integrations: ha_get_integration(integration_type="service")

  • An entry's panel commands: ha_get_integration(entry_id="abc123", include_ws_commands=True)

OPTIONS: with the component, options are the stored mapping as-is, so a field never set may be absent and a section's fields stay nested under the section key (e.g. a template helper's additional_options); values that match a secrets.yaml entry are returned as "**redacted**". Without it, include_schema=True reads options from the options form: unset fields at their schema default, a section's fields at the top level. With redact_secrets on, every option value of an entry that has an options flow is redacted unless include_schema=True reads the form that names the password fields; an entry without an options flow has no such form, so its option values come back as stored.

Each entry carries log_level: the canonical Python logger level name (DEBUG/INFO/WARNING/ERROR/CRITICAL) when the integration has a log-level override (set one with ha_set_integration(log_level=...)), or "DEFAULT" (uppercase sentinel) when no override is set; and log_level_raw: the original numeric level (e.g. 10 for DEBUG) when HA returned an int, None otherwise. This is distinct from the app side, where ha_get_app returns Supervisor's lowercase "default" literal — do not cross-compare.

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_get_integration"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax entries to return per page in list mode
queryNoWhen listing, search by domain or title.
domainNoFilter by integration domain (e.g. 'template', 'group'). When set, includes the full options/configuration for each entry.
offsetNoNumber of entries to skip for pagination
entry_idNoConfig entry ID to get details for.
device_idNoWith include_diagnostics=True, return the device-scoped diagnostics dump for this device instead of the full integration dump. Some integrations only expose config-entry-level dumps.
exact_matchNoUse exact substring matching for query filter. Set to False for fuzzy matching when the query may contain typos.
subentry_idNoExisting subentry ID used with include_subentry_schema=True to inspect a reconfigure flow.
subentry_typeNoIntegration-defined subentry type used with include_subentry_schema=True.
include_schemaNoWhen entry_id is set, also describe the options flow form as options_schema.fields: each field's type, current value and Home Assistant's help text. A flow that opens with a menu lists menu_options instead (ha_set_integration(entry_id=..., menu_choice=...) opens one), and a flow Home Assistant aborts gives aborted, plus reason_text when Home Assistant has a string for the reason. Only applies when supports_options=true. The flow is started, described and aborted; starting it runs the integration's own flow code, and some integrations act there (Sonoff LAN signs in to its cloud). For an integration's setup form, use ha_set_integration(domain=...).
include_optionsNoInclude the options object for each entry. Automatically enabled when domain filter is set. For UI-created flow-based helpers (template, group, utility_meter, derivative, ...), the current config — template body, group members, source entity, etc. — is here. Read through the ha_mcp_tools custom component; without it an entry that has an options flow comes back without options and a warning, and only include_schema on that entry reads them. With the component, prefer this over include_schema when you only need the current values; use include_schema when you also need the field types or selector metadata.
integration_typeNoWhen listing, keep only entries whose integration has this type, matched by Home Assistant itself (the manifest's integration_type, e.g. 'device', 'hub', 'service', 'helper'). Home Assistant does not reject an unknown type: for any type but 'helper' it also keeps entries whose integration it cannot find (e.g. a removed custom integration), so an unknown type returns only those.
diagnostics_fieldsNoTop-level keys to keep from the diagnostics data payload (e.g. ['home_assistant', 'issues']). Accepts a JSON list or comma-separated string. Only applies when include_diagnostics=True and the data payload is a dict. Unknown keys are dropped and listed under omitted_fields.
include_subentriesNoWhen entry_id is set, include config subentries for the integration entry.
include_diagnosticsNoWhen entry_id is set, also fetch the integration's diagnostics dump — integration-defined JSON (commonly includes redacted config, device list, state snapshots; exact top-level keys vary by integration), the same artifact as the UI's 'Download diagnostics'. Payloads can be large (Hue ~290 KB, ZHA/MQTT/ESPHome several MB) — pair with diagnostics_fields or diagnostics_truncate_at_bytes.
include_ws_commandsNoWhen entry_id is set, also list the integration's own '<domain>/' WebSocket commands (the API its panel uses, e.g. KNX's knx/get_knx_project) under ws_commands, each with the request schema Home Assistant registered for it. Send one with ha_set_integration(entry_id=..., ws_command=...). Needs the ha_mcp_tools custom component; without it a warning says the list is unavailable.
diagnostics_data_pathNoDotted path into the diagnostics data sub-tree (e.g. '<list-valued path>' for per-device records, 'home_assistant.version' for HA core version; the exact key path varies by integration version). Walks into the post-fields payload. Resolution failures replace data with null and surface data_path_error. Only applies when include_diagnostics=True.
show_advanced_optionsNoWhen include_subentry_schema=True, ask older Home Assistant versions to expose advanced flow options. No-op on HA 2026.6+; pending removal before HA 2027.6.
diagnostics_data_limitNoPagination window size for list-valued diagnostics_data_path results. When set with a list-resolved path, swaps data for a pagination envelope {path, items, offset, limit, total, has_more}. Default None returns the full resolved value. Only applies when include_diagnostics=True.
diagnostics_data_offsetNoPagination start index for list-valued diagnostics_data_path results. Ignored when diagnostics_data_path is unset, diagnostics_data_limit is unset, or the resolved value is not a list. Only applies when include_diagnostics=True.
include_subentry_schemaNoWhen entry_id is set, describe a config subentry flow's form as subentry_schema.fields (same shape as include_schema); the flow is aborted afterwards. Pair with subentry_type, and optionally subentry_id for the reconfigure form.
diagnostics_truncate_at_bytesNoByte cap on the serialized diagnostics payload (after diagnostics_fields and diagnostics_data_path have been applied). On hit, drops data and emits truncated=true, bytes_total, byte_cap, plus available_fields (when the capped value is a dict). Recommended starting point: 20000 bytes. Only applies when include_diagnostics=True.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv9.2.0

TDQS

A4.7/5.0
Behavior5/5

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

The annotations already declare readOnlyHint=true and destructiveHint=false, yet the description still adds substantial non-obvious behavior: include_schema starts and aborts a real options flow, and "some integrations act there (Sonoff LAN signs in to its cloud)." It also discloses secrets redaction rules, that diagnostics payloads can reach several MB (Hue ~290 KB, ZHA/MQTT/ESPHome several MB), and that several features require the ha_mcp_tools custom component or degrade to a warning.

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

Conciseness3/5

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

The front-loading and section labels (WHEN NOT TO USE, EXAMPLES, OPTIONS) are strong, but the closing paragraphs are dense unbroken prose about return-value semantics — stored options mapping, log_level/log_level_raw sentinels — that a separate output schema already carries. The log_level versus ha_get_app cross-comparison warning in particular is long for what it conveys.

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 22-parameter tool with no required parameters, the definition covers the list/detail split, the heavy optional diagnostics path, custom-component prerequisites, redaction under redact_secrets, and the side effects of schema inspection. Combined with an existing output schema, an agent has everything needed to call it correctly on the first attempt.

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 earns above that by explaining interactions the schema cannot: when include_options is auto-enabled (domain filter), why include_options is preferable to include_schema when only current values are needed, how diagnostics_data_path plus limit/offset swap data for a pagination envelope, and the integration_type quirk that unknown types silently match unfindable integrations. It stops short of a genuinely parameter-by-parameter guide, leaving some relationships to be inferred from examples.

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?

Opens with a specific verb+resource ("Get integration (config entry) information") and immediately splits the two operating modes: without entry_id it lists, with entry_id it returns details including options. It explicitly names the sibling ha_set_integration as the mutation counterpart, so an agent can distinguish read from write without opening either schema.

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?

Contains a labeled "WHEN NOT TO USE" block that routes entry changes and setup-form retrieval to ha_set_integration, and eight worked examples map concrete intents (search, password-field form, subentry reconfigure, diagnostics paging, service-only listing) onto exact parameter combinations. Both the when and the when-not are stated, which is the top of the scale.

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