Skip to main content
Glama

Manage HACS

ha_manage_hacs
Destructive

Install, update, or remove Home Assistant Community Store repositories, add custom repos, refresh release data, or accept the Marketplace warning.

Instructions

Manage HACS (Home Assistant Community Store) — install/update, remove, add custom repositories, or refresh repository information.

On Home Assistant 2026.11+ HACS is the built-in Marketplace; the tool uses whichever the instance has. This tool performs writes; to search the store or read repository details use ha_get_hacs_info. Use action="update_information" to run the HACS UI's "Update information" action ("Refresh information" in the Marketplace) — a forced re-fetch of one repository's release data from GitHub, so a pending update becomes visible to the store and its update entity immediately.

Examples:

  • Install latest: ha_manage_hacs(action="download", repository_id="441028036")

  • Install a version: ha_manage_hacs(action="download", repository_id="piitaya/lovelace-mushroom", version="v4.0.0")

  • Remove: ha_manage_hacs(action="remove", repository_id="owner/repo")

  • Add a custom repo: ha_manage_hacs(action="add_repository", repository="owner/repo", category="lovelace")

  • Refresh release data: ha_manage_hacs(action="update_information", repository_id="owner/repo")

  • Accept the Marketplace warning: ha_manage_hacs(action="accept_warning", confirm=True)

Caveats: Installing an integration usually needs a Home Assistant restart to activate; new Lovelace cards need a browser cache clear. add_repository requires owner/repo format plus a matching category. Removing an integration deletes its files but the loaded module persists until the next Home Assistant restart — delete its config entries first (ha_remove_helpers_integrations). HACS refreshes custom repositories on its own only about every 48 hours (the Marketplace only with a connected GitHub account), so update_information is the way to surface a just-published release. The Marketplace refuses installs until the user this server connects as has accepted its first-run warning; Home Assistant keeps that per user, so the user's own acceptance in the UI does not cover this server. Ask the user whether they have read it (Settings > Marketplace) and accept it before accept_warning. Adding a repository needs a GitHub account the user connects in the Marketplace panel.

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

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "ha_manage_hacs"
  }
}

Input Schema

NameRequiredDescriptionDefault
actionYes'download' to install/update, 'add_repository' to register a custom repo, 'remove' to uninstall a downloaded repo, 'update_information' to refresh a repository's release data from GitHub, or 'accept_warning' to accept the Marketplace's first-run warning for the user this server connects as
confirmNoaction='accept_warning': True once the user has said they read the Marketplace's first-run warning and accept it
versionNoSpecific version to install (action='download')
categoryNoRepository category (action='add_repository'). One of the categories the store reports (search's store.categories); 'lovelace' means 'plugin' (dashboard cards).
repositoryNoGitHub repo 'owner/repo' to add (action='add_repository')
repository_idNoNumeric HACS ID or 'owner/repo' path (action='download' / 'remove' / 'update_information')
confirm_replace_built_inNoMarketplace only (action='download'): install a repository that replaces the built-in integration of the same domain. Set it only after the user agrees.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv9.2.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds substantial behavior beyond them: restart requirements after installing an integration, browser cache clears for Lovelace cards, the fact that removed integration modules persist until restart, the ~48h autonomous refresh interval, and the per-user nature of the Marketplace first-run warning. These are operational consequences an agent could not infer from the 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 purpose, then examples, then caveats — a sensible progression with no filler in the main body. The trailing Claude Desktop timeout workaround is long and only relevant to one client, which slightly dilutes focus, though it is clearly scoped as environment-specific.

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 seven-parameter destructive tool with an output schema already covering return values, the description covers prerequisites, side effects, sequencing (delete config entries before removing an integration), and authorization requirements (per-user warning acceptance, GitHub account connection). Nothing an agent needs to call it safely is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents formats for action, repository_id ('owner/repo' or numeric ID), and category. The description reinforces a few constraints (owner/repo format, matching category, confirm gating) but adds little meaning that isn't already in the parameter descriptions, so the baseline of 3 applies.

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 description names a specific resource (HACS / Home Assistant Community Store) and enumerates the exact operations: install/update, remove, add repository, refresh info. It explicitly distinguishes itself from the read-only sibling ha_get_hacs_info, so an agent can route correctly 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?

It states when to use this tool versus the alternative ('to search the store or read repository details use ha_get_hacs_info'), and gives a per-action example block covering all five enum values, including the non-obvious update_information semantics. Explicit guidance on when add_repository vs download applies ('requires owner/repo format plus a matching category') is also present.

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