Skip to main content
Glama

Get Dashboard

ha_config_get_dashboard
Read-onlyIdempotent

Lists Lovelace dashboards, reads a dashboard or single view config, or searches cards by entity, type, heading, or text. Returns jq and python paths for editing matches.

Instructions

Get Lovelace dashboards: list them, read one config, or search their cards.

Not for a render alone: ha_get_dashboard_screenshot (screenshot beta feature) returns images without the config. Not for entity discovery: use ha_search.

The parameters pick the mode:

  • list_only=True: storage and YAML dashboards alike.

  • Any of query / entity_id / card_type / heading searches cards and header cards, AND-ing the criteria, in url_path or, when it is omitted, every storage dashboard. View badges answer entity_id and query, and heading excludes them. Cards nested at any depth count, including custom cards' own keys such as groups[].cards[].card. Nesting is found heuristically, under the keys cards, card, custom_fields and states; a card under any other key is read only as its parent's text, by query. Each match has a jq_path and a python_path to append to config in ha_config_set_dashboard(python_transform=...), e.g. f'config{m["python_path"]}["icon"] = "mdi:x"'. Each match carries its dashboard's url_path and config_hash; a one-dashboard search also returns the config_hash at the top level.

  • Otherwise the full config of url_path (the default dashboard when omitted) is returned; with view_path only that view, while config_hash still covers the full config. stored_config is false (config null) when Home Assistant holds no config for the dashboard.

Caveats: config_hash stays the same across reads of an unchanged config. Searches stop at 200 matches (truncated). A search across dashboards skips YAML dashboards (HA resolves !secret in them) and, without a current ha_mcp_tools component, the default dashboard (with a warning); name either by url_path. Strategy dashboards have no stored cards to search. An unknown view_path errors and lists the available ones.

EXAMPLES:

  • List all dashboards: ha_config_get_dashboard(list_only=True)

  • Get one view only: ha_config_get_dashboard(url_path="lovelace-mobile", view_path="office")

  • Find cards by entity (wildcards allowed): ha_config_get_dashboard(url_path="my-dash", entity_id="sensor.temperature_*")

  • Find heading: ha_config_get_dashboard(url_path="my-dash", heading="Climate", card_type="heading")

  • Which dashboards use an entity: ha_config_get_dashboard(query="light.bedroom")

  • Fields of a card type before writing one (omit card_type to list types): ha_config_get_dashboard(card_type="tile", describe=True)

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

Input Schema

NameRequiredDescriptionDefault
queryNoSearch: text or entity ID contained in any value a card holds (case-insensitive); the matching values are listed under `matched`.
headingNoSearch: cards whose heading/title contains this text (case-insensitive).
describeNoReturn card_type's fields from HA's card editor
url_pathNoDashboard URL path (e.g. 'lovelace-home'); 'default' for the default dashboard.
card_typeNoSearch: cards of this type, e.g. 'tile'; 'badge' selects view badges instead (alone, it lists them all). With describe=True: the type to describe.
entity_idNoSearch: cards whose entity/entities field holds this entity ID; '*' matches any run of characters (including none) and the whole ID must match (e.g. 'sensor.temperature_*').
list_onlyNoList every dashboard's metadata instead of reading one; ignored when a search parameter is given.
view_pathNoGet mode: return ONLY the view whose Lovelace views[].path matches (response carries 'view' + 'view_index' instead of the full 'config'). With include_screenshot, also selects the view to render.
force_reloadNoGet only: bypass the config cache (searches always read fresh config).
include_configNoSearch: include each matched card's own config. A container's body includes its nested cards, which are also matches, so nested stacks multiply the payload. Withheld, with a warning, for a dashboard not provably storage-mode (a YAML config may carry resolved !secret values).
include_screenshotNoGet mode only: also return rendered image(s) of the dashboard for visual verification. Requires the 'dashboard screenshot' beta feature + engine app (add-on)/sidecar. If the feature is disabled the config is returned with a warning; if the engine is configured but the render fails, the call errors.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv9.2.0

TDQS

A4.9/5.0
Behavior5/5

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

Although annotations already mark this as a safe read operation, the description adds substantial behavior beyond them: config_hash stability, the 200-match truncation limit, YAML dashboard skipping for cross-dashboard searches, default-dashboard warnings, strategy dashboards lacking stored cards, and unknown view_path errors listing available views.

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?

The description is front-loaded with purpose and exclusions, then organized by mode and caveats, with examples at the end. It is dense and long, but most sentences carry necessary operational detail for an 11-parameter tool; a slightly tighter structure would improve scanability.

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?

Given the 11 parameters, absence of an output schema, and rich read-only annotations, the description covers modes, caveats, error behavior, return-shape hints (config, view, view_index, config_hash, truncated), and examples. An agent has everything needed to invoke it correctly.

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

Parameters5/5

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

With 100% schema coverage the baseline would be 3, but the description adds mode-selection semantics and cross-parameter interactions the schema does not: search parameters are AND-ed, entity_id supports wildcards, heading excludes badges, card_type='badge' lists view badges, describe=True uses card_type as a type to describe, and include_config has a storage-mode safety caveat.

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?

The opening sentence states the specific resource (Lovelace dashboards) and the three modes: list, read one config, or search cards. It explicitly distinguishes itself from sibling tools (ha_get_dashboard_screenshot for renders, ha_search for entity discovery), so an agent can select it without opening any 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?

The description gives explicit when-not-to-use rules ('Not for a render alone', 'Not for entity discovery') and names the alternatives. It then explains exactly how parameters select each mode, including list_only, search criteria, and default read behavior, with concrete examples.

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