Skip to main content
Glama

Set Dashboard Resource

ha_config_set_dashboard_resource
Destructive

Create or update Home Assistant dashboard resources using inline JavaScript/CSS, external URLs, or search/replace edits; aborts on failed edits or hash mismatch.

Instructions

Create or update a dashboard resource (inline code or external URL).

Provide exactly one of:

  • edits: Search/replace edits on an existing inline resource. Any failing edit (or a config_hash mismatch) aborts the whole call and saves nothing. Prefer this over content= for small changes to a large card: only the changed text is sent.

  • content: Inline JavaScript or CSS code (embedded in the resource URL as a data: URI — no file storage or external hosting involved). Supports 'module' and 'css' types only; URLs are deterministic (same content = same URL); up to ~128KB. Content must be self-contained: a data: URI has no base URL, so relative imports inside a module and relative url() references inside CSS cannot resolve (use fully-qualified URLs instead). If Home Assistant is behind a reverse proxy that injects a Content-Security-Policy without 'data:' in script-src/style-src, the browser blocks these resources: this call still succeeds and the card simply never renders. Register the code as a file and use url='/local/...' on such a deployment. (HA itself ships no CSP.)

  • url: External resource URL — /local/... (/config/www/; Marketplace cards: /local/community/...), /hacsfiles/... (HACS cards) or https://... (CDN). Supports all types: 'module', 'js', 'css', 'html'.

EXAMPLES:

  • Inline: ha_config_set_dashboard_resource(content="class MyCard extends HTMLElement { ... } customElements.define('my-card', MyCard);", resource_type="module")

  • Store cards need no call: in storage mode HACS and the Marketplace register the resource on install (adding it again duplicates it); with YAML-mode resources, list it under lovelace: resources: in configuration.yaml instead.

  • Update: ha_config_set_dashboard_resource(url="/local/my-card-v2.js", resource_type="module", resource_id="abc123")

  • Patch: ha_config_set_dashboard_resource(resource_id="abc123", edits=[{"old": "color: red", "new": "color: blue"}], config_hash="<_config_hash from the list>")

Inline writes return the stored content's config_hash.

After adding a resource, a browser cache clear or hard refresh (Ctrl+Shift+R) is needed to load it.

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.

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

Input Schema

NameRequiredDescriptionDefault
urlNoURL of the resource.
editsNoSearch/replace edits for an existing inline resource, applied in order. Requires resource_id; resource_type is ignored and the stored type is kept.
contentNoJavaScript or CSS code to host inline.
config_hashNoWith edits: refuse the patch unless the stored content has this hash when read, just before the write (the list's _config_hash with include_hash=True, or a previous write response's config_hash). A preflight check only: a change made by another client after that read is not detected and can be overwritten.
resource_idNoResource ID to update. If omitted, creates a new resource. Get IDs from ha_config_list_dashboard_resources()
resource_typeNoResource type, validated by Home Assistant: 'module' for ES6 modules (modern cards), 'js' for legacy JavaScript (older custom cards), 'css' for stylesheets (themes, global styles), 'html' for HTML importsmodule

Output Schema

NameRequiredDescriptionDefault

No arguments

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?

Goes well beyond the destructiveHint=true / idempotentHint=false annotations: it discloses that any failing edit or hash mismatch aborts the whole call and saves nothing, that data: URIs are deterministic and capped at ~128KB, that CSP-blocked resources still report success but never render, and that a hard refresh is required after adding. These are exactly the failure modes an agent cannot infer from annotations.

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 core rule and organized into scannable per-mode bullets, so structure is strong. The final Claude Desktop timeout paragraph is the one section that sprawls and is tangential to the tool's contract, keeping this from a 5.

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?

An output schema exists, so return values need no explanation, yet the description still notes that inline writes return the stored content's config_hash. For a destructive, non-idempotent write with six optional parameters, everything an agent needs — mode selection, atomicity, limits, post-write behavior — is covered.

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?

Schema coverage is already 100%, so the baseline would be 3, but the description adds real meaning: the mutual-exclusivity rule across url/content/edits, the type support matrix (content accepts only 'module' and 'css', url accepts all four types), and why config_hash matters (abort-on-mismatch, with the caveat that it is preflight-only). It also explains that resource_type is ignored for edits.

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?

"Create or update a dashboard resource (inline code or external URL)" gives a specific verb pair, the resource, and the two supported content modes. It is immediately distinguishable from siblings like ha_config_list_dashboard_resources and ha_config_delete_dashboard_resource.

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?

Explicitly states "Provide exactly one of" the three modes, tells the agent when to prefer edits over content ("small changes to a large card"), and gives an exclusion: store-managed HACS/Marketplace cards need no call because re-adding duplicates them. It also routes to url='/local/...' when a reverse proxy injects CSP — a concrete when-not condition for the content path.

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