Install type

Run Standalone ha-mcp  MCP Server outside Home Assistant.

 

Note

Earlier solutions (such as the standalone ha-mcp project) usually ran as an external Python process:

Claude
      │
Standalone ha-mcp Server
      │
REST/WebSocket
      │
Home Assistant

 

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.

Table of Contents

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
         │
┌────────▼────────┐
│ Standalone  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.

 

Start Docker Container

docker run -d --name ha-mcp -p 8086:8086 -v ha-mcp-data:/home/mcpuser/.ha-mcp -e HOMEASSISTANT_URL={{HOMEASSISTANT_URL}} -e HOMEASSISTANT_TOKEN={{HOMEASSISTANT_TOKEN}} ghcr.io/homeassistant-ai/ha-mcp:latest ha-mcp-web

Server will be at: http://YOUR_IP:8086/mcp

detail:https://homeassistant-ai.github.io/ha-mcp/setup/?method=docker&client=claude-desktop&scope=local&platform=linux

 

 

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

source code:https://github.com/homeassistant-ai/ha-mcp/tree/master/custom_components/ha_mcp_tools

 

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 stable release from the latest release

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

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

 

Home Assistant MCP Server Add-on doc

https://github.com/homeassistant-ai/ha-mcp/blob/master/homeassistant-addon/README.md

 

Runs the full ha-mcp server inside Home Assistant.

Home Assistant MCP Setup：https://homeassistant-ai.github.io/ha-mcp/setup/?method=ha-component&client=open-webui&scope=local

 

LM Studio +ollama+unofficial HA-MCP Server+ Claude Code

https://www.xda-developers.com/i-connected-my-local-llm-to-home-assistant-through-mcp/

Comments


Comments are closed