LibreAI / AI Agents / ha-mcp
// agents · homeassistant-ai/ha-mcp

ha-mcp

The unofficial Home Assistant MCP server — control and automate your smart home from any AI assistant.

★ 5.0k stars⑂ 231 forksMITupdated 2026-10
▦ visual — this project's README ships no embeddable screenshot,
so here's a placeholder. The guide below is complete regardless.
// project facts

Project facts

ha-mcp is an open-source ai agents project by homeassistant-ai (homeassistant-ai/ha-mcp on GitHub). It has 4,977 GitHub stars and 231 forks, is released under the MIT license, and was last updated on GitHub on 8 October 2026.

GitHub stars
4,977
Forks
231
License
MIT
Last updated on GitHub
8 October 2026
Category
AI Agents
Listing
Full install guide
Official site
Official site
// how it works

How it works

  1. Clarify what your assistant should do

    Decide which parts of your home the assistant may see and control, and which client (Claude or another MCP client) you will use.

  2. Choose an install method

    Pick one: the in-process HACS integration, the Docker HTTP server, or the uvx/PyPI server — running more than one is not supported.

  3. Connect to Home Assistant

    Point the server at your Home Assistant URL with a long-lived access token (an administrator's is recommended), or finish the in-app setup.

  4. Ask your first command

    Ask your assistant about your home — list lights, check a sensor, run a script — through the MCP tools.

// features

Why people love it

Full MCP access to Home Assistant

Exposes your Home Assistant entities and services as MCP tools so assistants can read state and take action.

In-process integration option

Can run inside Home Assistant itself via HACS, replacing the other install methods, with an admin-only HA-MCP settings panel in the sidebar.

Remote access via webhook

A Nabu Casa remote webhook URL lets cloud MCP clients reach your home securely; local-only mode disables the webhook entirely.

Flexible authentication

Options include the secret URL as credential, Home Assistant account sign-in (ha_auth), or OIDC via an external identity provider such as Authentik, Keycloak or Auth0.

Tool search for small contexts

An optional ENABLE_TOOL_SEARCH mode defers the large tool catalog behind a search interface so models with small context windows (or capped clients) can still work.

Docker and PyPI servers

Run ghcr.io/homeassistant-ai/ha-mcp as an HTTP server, or the published ha-mcp package with uvx, pointed at your Home Assistant.

Advertisement
// run it

Run it yourself

  1. Clone the repository

    Clone ha-mcp if you want the source or the manual integration files.

    git clone https://github.com/homeassistant-ai/ha-mcp.git
    cd ha-mcp
  2. Install with the one-command installer

    Run the installer for your OS and MCP client — this example wires up Claude Code on Linux.

    curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh
    # For Claude Code: curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code
  3. Or run the server package

    Alternatively, serve ha-mcp over HTTP with uvx against your Home Assistant instance.

    uvx ha-mcp@latest # see README for the exact command
// use cases

What you can build

Advertisement
// faq

Questions, answered

Who maintains ha-mcp?

ha-mcp is a community project from homeassistant-ai; it is unofficial and not affiliated with the Home Assistant project itself.

Is ha-mcp free?

Yes — it is open source under the MIT license. You need your own Home Assistant instance (also free and open source).

Does it need a paid API key?

No API key is required; the server authenticates to your Home Assistant with a long-lived access token you create. Remote access can use your Nabu Casa account if you have one.

How does it compare to Home Assistant's built-in Assist or LLM integrations?

Those live inside Home Assistant's own conversation features; ha-mcp exposes your home to external MCP clients and agents (Claude and others) with fine-grained install and auth options.

How do I get started?

Pick one install method — HACS integration is the most integrated — run the installer or add the integration, and connect your MCP client.

// keep exploring

Similar tools

AI Agents

google_workspace_mcp

Control Gmail, Calendar, Docs, Sheets, Drive and more from AI — a full Google Workspace MCP server.

★ 3.3k starsMIT
View guide →
AI Agents

deep-research

Deep Research with any LLM: in-depth reports in minutes, with an SSE API and MCP server built in

★ 4.7k starsMIT
View guide →
AI Agents

lamda

FIRERPA / LAMDA — full-stack Android device control: remote desktop, automation, MITM, Frida and MCP.

★ 8.6k starsMIT
View guide →
AI Agents

mcp

An MCP server that puts Hyperbrowser's browsers behind the protocol.

★ 789 starsMIT
View guide →
AI Agents

github-mcp-server

GitHub's official MCP server — let AI tools work with repos, issues and pull requests

★ 33.4k starsMIT
View guide →
AI Agents

dbhub

A token-conscious MCP server that connects AI tools to Postgres, MySQL, SQLite and more.

★ 3.6k starsMIT
View guide →
// alternatives

Alternatives in AI Agents

The most-starred other AI Agents projects in the LibreAI catalogue — the realistic shortlist if ha-mcp is not the right fit.

Get ha-mcp

Free and open — grab the source, star the repo, and start creating.