Claude Code for Home Assistant(ha-mcp Server directly inside Home Assistant)

Claude Code for Home Assistant

Is there a guide to setup home assistant with MCP and integrate with Claude？

 

I created an guide that integrates Claude Code (Anthropic’s AI assistant) directly into Home Assistant. With it, you can create automations, debug configurations, and manage your smart home using natural language through a browser-based terminal.

 

Install type

Run MCP Server directly inside Home Assistant.

 

Note

Newly solutions  usually ran as an internal Python process inside Home Assistant.

 

ha-mcp-integration is a native Home Assistant integration that embeds an MCP (Model Context Protocol) Server directly inside Home Assistant.

offcial website:https://github.com/homeassistant-ai/ha-mcp-integration

download:https://codeload.github.com/homeassistant-ai/ha-mcp-integration/zip/refs/tags/v1.3.0

Usage examples

claude “Create an automation to turn off lights when I leave home”

Create an automation that turns on the bedroom AC when the temperature exceeds 28°C.

How does it work?

The ha-mcp-integration uses ha-mcp (Model Context Protocol) server which allows Claude to:

Query entity states

Control devices

List available services

Access the entire Home Assistant API

Besides the built-in tools, the server can expose tools coming from MCP servers.

 

ha-mcp-integration

The integration starts an MCP Server inside Home Assistant..

The integration registers MCP Tools

AI Mcp client connects via MCP.

Architecture

                 AI Client
       (ChatGPT / Claude / Cursor)
                    │
          MCP Protocol (HTTP/SSE)
                    │
        ┌────────────────────────┐
        │ Home Assistant         │
        │ ha-mcp-integration     │
        │                        │
        │  MCP Server            │
        │  Tool Registry         │
        │  Authentication        │
        └──────────┬─────────────┘
                   │
          Home Assistant Core
                   │
      ┌────────────┴─────────────┐
      │ States                   │
      │ Services                 │
      │ Devices                  │
      │ Areas                    │
      │ Automations              │
      │ Scripts                  │
      │ History                  │
      └──────────────────────────┘

 

 

ha-mcp-integration:Full MCP Server running inside Home Assistant. AI clients connect directly to it.

ha_mcp_tools:A library of MCP tools used by the MCP Server.

ha-mcp-integration
        │
        ├── starts MCP Server
        │
        └── uses ha_mcp_tools
                 │
                 ├── call_service
                 ├── get_state
                 ├── list_entities
                 ├── search_devices
                 └── ...

 

ha-mcp-integration does not "think up" automations by itself. Instead, it exposes Home Assistant capabilities as MCP tools, allowing an AI (ChatGPT, Claude, Cursor, etc.) to inspect your Home Assistant configuration and then create or modify automations.

 

 

Requirements

Home Assistant Docker

Anthropic account 

Inside home assistant

Installation ha-mcp-integration

 

ha-mcp-integration=HA-MCP Custom Component

Step 1: Download the HA-MCP Custom Component:

https://github.com/homeassistant-ai/ha-mcp-integration/releases

wget https://github.com/homeassistant-ai/ha-mcp-integration/archive/refs/tags/v1.3.0.zip

copy custom_components/ha_mcp_tools/ into config/custom_components/

 

Step 2: Restart home assistant:

 

Step 3: Install the HA-MCP Custom Component:

 

Choose Add HA-MCP Server.it 

 

 

 

 

 

 

 

Copy the connect URL for AI Client

http://192.168.2.125:8123/config/integrations/integration/ha_mcp_tools

Copy the connect URL from the entry's Configure screen (Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure) 

 

 

Verify the Target Server is Active:

http://192.168.2.125:9584/private_QQz2CLU3n8xRQ1

HA-MCP server is up and running!

To connect, paste the full URL (including the /private_... key) into the
connector or MCP settings of your AI/LLM client. No username or password required.
Setup instructions: https://homeassistant-ai.github.io/ha-mcp/

--- Seeing this page? Your URL is set up correctly ---

If this page loads in your browser, the MCP server is reachable and the
URL is correct. If your AI client still cannot connect, the problem is
not on HA-MCP's side. Common causes:

- Geo / country blocking in your reverse proxy / CDN (Cloudflare, NGINX,
  Traefik, Zoraxy, etc.). Most AI/LLM services connect from US-based
  cloud infrastructure, so if you block US IP addresses (or only allow
  your own country), that is why your client cannot connect. Allow your
  provider's IP ranges (or your client's egress IPs). For example,
  Claude.ai connects from Anthropic's network, 160.79.104.0/21.
- WAF, bot-blocking, or rate-limiting rules on the proxy that drop or
  challenge the request.
- The AI client's network can sometimes be spotty -- you may just need
  to try connecting again.
- The AI client itself refusing certain domains or proxy providers on
  its end. This is rare and outside your control; try a different
  hostname or proxy if you suspect it.

Your proxy's access logs will show the blocked attempt -- look for the
request from your AI provider's IP (e.g. an Anthropic 160.79.x.x address).

--- Cloudflare Users ---

If your LLM cannot connect, Cloudflare's "Block AI training bots"
setting is the most common cause. To disable it:

1. Log in to Cloudflare (https://dash.cloudflare.com)
2. In the left sidebar, click Domains, then click Overview
3. Click on the domain you use for connecting to Home Assistant
4. On the right side, find "Control AI Crawlers"
5. Under "Block AI training bots", open the dropdown
6. Select "do not block (allow crawlers)"

Screenshot of the setting:
https://homeassistant-ai.github.io/ha-mcp/images/cloudflare-ai-crawlers-setting.jpg