Home Assistant MCP Server

About

Automatic summary of the docs and configuration of homeassistant-ai/ha-mcp. Something wrong, or are you the maintainer and want your own text here? Get in touch

Supports

• Opens in the sidebar Its own page opens inside Home Assistant.

• Actively maintained Its author released or pushed a change in the last six months.

Setting it up

Add its app repository under Settings, Apps, then install and start it.

From the docs

Permissions

• Host networkUses the host's network directly instead of its own.
• Home Assistant APICan read and control Home Assistant.
• Supervisor APICan talk to the Supervisor, which manages apps and the system.

Network

• 9583/tcp

Configuration

• Verify TLS certificatesVerify the Home Assistant server's TLS certificate. Turn this off only on a trusted network, for a self-signed certificate or a hostname mismatch: it weakens transport security.
• Home Assistant tool concurrencyOptional limit on outer Home Assistant tool calls across all sessions. Internal REST, WebSocket, and per-tool fan-out concurrency is unchanged. 0 keeps unlimited behavior. A call waiting for capacity fails after 60 seconds. Range 0–32.
• Backup hint levelHow strongly AI assistants are told to suggest a full Home Assistant backup before risky changes. It changes only this hint; automatic edit backups have their own setting.
• Custom server instructionsText sent to every AI assistant that connects, as part of the MCP server instructions — for example where household notes are kept and when to read or update them. Also part of the prompt of Home Assistant conversation agents (Assist) that use this toolset. Use it for guidance that should reach all your clients at once; keep it short and free of secrets. Leave empty to add nothing. Requires restart; clients see the change when they reconnect.
• Enable tool searchReplace the full tool catalog with search-based discovery. Reduces idle context by roughly 90%, to about 5K tokens. ⚠️ Do NOT enable this in clients with their own built-in tool search / deferred tools (claude.ai, Claude Desktop, Claude Code) — the two search layers conflict, and the client's built-in tool search is the better choice there; leave this off. Whether tools are deferred depends on your client and model combination: use this when your setup loads the full catalog up front — models without native deferred tools (e.g. Gemini, OpenAI-compatible local models, Claude Haiku), clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI), or smaller context windows. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily. Tools are found via ha_search_tools and executed via categorized proxies (read/write/delete). Requires an app (add-on) restart to take effect — then reconnect or refresh the MCP server in your AI client so it reloads the tool list. Restarting the app (add-on) alone does NOT refresh a client's cached tool list; this applies after changing any setting here.
• Tool search max resultsMaximum number of hidden tools returned per ha_search_tools call when tool search is enabled; a pinned tool that ranks inside that top count is added as a short name-only entry on top of it. Lower values (2-3) save context tokens but may miss relevant tools. Requires restart. Range 2–10.
• Enable Tool Security Policies (advanced)Gate high-stakes tool calls (lock/alarm control, automation writes, etc.) behind user approval. When a guarded tool is called, the agent tells the user to open the Tool Security Policies tab in the web UI and click Approve before the call proceeds. Per-tool rules with optional argument conditions are configured in the Tool Security Policies tab. Off by default. Requires restart to take effect.
• Let AI agents edit tool security policiesRegisters the ha_manage_security_policy tool, which lets connected AI agents read and rewrite the tool security policies — including removing approval gates. Off by default. Independent of the Tool Security Policies option above: this controls who can edit the rules, not whether they are enforced. The tool cannot see or decide pending approvals. To keep a human in the loop, gate the tool before enabling it: switch on "security gated" for Manage Security Policy in the Tools tab of the web UI. Requires restart to take effect.
• Read Only ModeToggles all write tools off, and removes ability for tools to make any write or destructive calls. Mixed read/write tools — backups, Apps (add-ons), energy preferences, voice pipelines, and code mode when enabled — stay available with their write operations blocked. Same toggle as the web UI Tools tab. Off by default. Requires restart to take effect.
• Redact SecretsRedacts secrets from tool responses before they reach the AI assistant. App (add-on) options and integration fields marked as passwords are replaced with a set/empty marker (so "is this credential configured?" stays answerable), and other tool responses are scrubbed of secret values the server has already seen (values shorter than 6 characters are skipped, since replacing tiny fragments would corrupt unrelated output). Other fields are not detected, except private keys in app options and the app option names listed below. Off by default.
• Extra app option keys to redactApp (add-on) option names to redact like password fields, for apps whose schema stores a secret as plain text (for example backup_password). Separate names with commas or new lines. A name applies to every app; write app_slug:name to limit it to one app. Naming an option group covers every option in it. Used only while Redact Secrets is on. Empty by default.
• Attach best-practice skills on writesMaster switch for the write-tool skill content delivery feature (issue #1182). When enabled (default), the six config write tools (automations, scripts, scenes, helpers, dashboards, raw YAML) attach the canonical Home Assistant best-practice reference files under skill_content on every successful write, plus auto-embed any reference sections cited by best-practice warnings. Each tool also exposes a per-call MandatoryBPS parameter the agent can set to false on subsequent calls once it has the content. When this master switch is off, NO skill_content goes out regardless of the per-call parameter or BP warnings. Recommended ON as the first choice; disable only for models with very small context windows. Turning this off may degrade write accuracy. Requires restart to take effect.
• Strict best-practices modeStrict mode: prevents the client from using the tool until it can prove that it read the best practices. While on, the six best-practice write tools (automations, scripts, scenes, helpers, dashboards, raw YAML) are blocked and return an error directing the client to read the best-practices skill via ha_get_skill_guide and pass back the acknowledgment key it obtains there. While on, the ha_get_skill_guide tool is locked enabled — it is the only publisher of the acknowledgment key. Child of the "Attach best-practice skills on writes" option above and inert while that parent is off. Requires restart to take effect.
• Auto-backup editsSave a snapshot of an entity before each write or delete tool call changes it. While this is off, the file and raw-YAML tools (ha_write_file, ha_delete_file, ha_config_set_yaml) refuse to write.
• Auto-backup throttle (minutes)How often auto-backup may capture the same entity. 0 captures on every write; N above 0 captures at most one snapshot per N minutes per entity. Range 0–1440.