Skip to main content
Glama
homeassistant-ai

Home Assistant MCP Server

Official
by homeassistant-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Manage HACS

ha_manage_hacs
Destructive

Manage HACS by installing, updating, removing, adding custom repositories, or refreshing release data to surface pending updates.

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")

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 connected user has accepted its first-run warning, and adding a repository needs a connected GitHub account; both are steps the user takes 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.

Input Schema

NameRequiredDescriptionDefault
actionYes'download' to install/update, 'add_repository' to register a custom repo, 'remove' to uninstall a downloaded repo, or 'update_information' to refresh a repository's release data from GitHub
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. Changed3 schema fields changedv9.0.0
    • changedInput schema / properties / category / anyOf
      Previous value: -[
-  {
-    "enum": [
-      "integration",
-      "lovelace",
-      "theme",
-      "appdaemon",
-      "python_script"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • changedInput schema / properties / category / description
      Previous value: -"Repository category (action='add_repository')"New value: +"Repository category (action='add_repository'). One of the categories the store reports (search's store.categories); 'lovelace' means 'plugin' (dashboard cards)."
    • addedInput schema / properties / confirm_replace_built_in
      Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Marketplace only (action='download'): install a repository that replaces the built-in integration of the same domain. Set it only after the user agrees."
+}
  2. Changed3 schema fields changedv8.2.0
    • changedInput schema / properties / action / description
      Previous value: -"'download' to install/update, or 'add_repository'"New value: +"'download' to install/update, 'add_repository' to register a custom repo, 'remove' to uninstall a downloaded repo, or 'update_information' to refresh a repository's release data from GitHub"
    • changedInput schema / properties / action / enum
      Previous value: -[
-  "download",
-  "add_repository"
-]New value: +[
+  "download",
+  "add_repository",
+  "remove",
+  "update_information"
+]
    • changedInput schema / properties / repository_id / description
      Previous value: -"Numeric HACS ID or 'owner/repo' path (action='download')"New value: +"Numeric HACS ID or 'owner/repo' path (action='download' / 'remove' / 'update_information')"
  3. First observedv7.14.2

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already say destructive/write/non-idempotent/openWorld, and the description adds substantially beyond that: restart required after integration install, browser cache clear for Lovelace, files deleted but module persisting until restart, Marketplace installs blocked until the first-run warning is accepted, and add_repository requiring a connected GitHub account. Even the Claude Desktop 4-minute timeout hang and retry/read-back workaround is disclosed.

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 ordering with no dead sentences. It is on the long side, and the Claude Desktop timeout paragraph is verbose relative to the core install/remove semantics, though it still earns its place for troubleshooting.

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?

With six parameters, destructive semantics, and an output schema already covering return values, the description fills every operational gap: post-install restart, cache clearing, dangling config entries, refresh cadence, and permission prerequisites. An agent could invoke any of the four actions correctly from this text alone.

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 a 3 baseline applies, but the description adds real semantics: `repository_id` accepts either numeric HACS IDs or `owner/repo` (shown across examples), `add_repository` requires `owner/repo` plus a matching `category`, and `confirm_replace_built_in` is gated on explicit user agreement. The per-action mapping of parameters is sparser in prose than in the schema, so it stops short of 5.

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?

Specific verb set and resource: install/update, remove, add custom repositories, refresh release data on HACS. It explicitly names the sibling it is not (`ha_get_hacs_info` handles search/read) and covers the 2026.11+ Marketplace rename, so an agent can distinguish it from any other tool without opening a 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?

Explicit routing is given: writes here, searching/reading goes to `ha_get_hacs_info`, and deleting lingering integration config goes to `ha_remove_helpers_integrations`. The `update_information` action is explained as the way to surface a just-published release when the ~48h auto-refresh hasn't happened, which is exactly the when-to-use decision an agent needs.

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