Using Claude Code to manage your Home Assistant config step by step

Published Aug 3, 2026

This project provides a seamless integration between Home Assistant and Claude AI via the Model Context Protocol (MCP), enabling using Claude Code to manage your Home Assistant config through natural language step by step.

Prerequisites
Architecture
Installation
Usage Examples

Prerequisites

Home Assistant ha-mcp MCP Server

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

Integration

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

AI client

Claude Desktop

Architecture

┌─────────────────┐
│   Claude AI     │
│  (Sonnet 4.5)   │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│   MCP Server    │
│  (WebSocket)    │
└────────┬────────┘
         │ REST API
         │
┌────────▼────────┐
│ Home Assistant  │
│   (v2026.7)    │
└─────────────────┘

MCP server connects to my HA instance through a Long-lived access token to access the Home Assistant API, giving it the ability to search entities, read automation traces, reload configs, and query device states.

ha-mcp is a standalone server built for configuring, building, and debugging your smart home

Installation

step 1.Start MCP server

Runs the ha-mcp server.

docker pull ghcr.io/homeassistant-ai/ha-mcp:latest


docker run -d \
  --name ha-mcp \
  --restart unless-stopped \
  -p 9000:9000 \
  -e HOMEASSISTANT_URL=http://192.168.1.100:8123 \
  -e HOMEASSISTANT_TOKEN=xxxxxxxxxxxxxxxx \
  -e MCP_PORT=9000 \
  ghcr.io/homeassistant-ai/ha-mcp:latest \
  ha-mcp-web

Docker (HTTP server): run ghcr.io/homeassistant-ai/ha-mcp in HTTP mode, pointed at your Home Assistant URL and a long-lived token.

step 2.Install HA-MCP Custom Component in Home Assistant

To add the Model Context Protocol Server service to your Home Assistant instance, use this Integration:

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

step 3.Create a long-lived access token in Home Assistant

You may create a Long-lived access token to allow the client to access the Home Assistant API.

Go to User profile > Security tab,select Create token.

step 4.Configure Claude

An LLM application acts as a client and can connect to multiple MCP servers to provide context.

{
  "mcpServers": {
    "homeassistant": {
      "type": "http",
      "url": "http://localhost:9090",
      "headers": { "Authorization": "Bearer your-ha-access-token" }
    }
  }
}

Usage Examples

Automation Creation

"Create an automation that turns off all lights when I leave home"
"Set up a morning routine at 7 AM with lights and coffee machine"
"Alert me when the washing machine finishes"

useful links

https://homeassistant-ai.github.io/ha-mcp

download from the latest release

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

Runs the full ha-mcp server inside Home Assistant.