io.github.homeassistant-ai/ha-mcp

Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants.

io.github.homeassistant-ai/ha-mcp · Repository · version 9.1.2 · 5.5k stars · listed from registry

Install

The sweep installs into a clean prefix, but this is the command a user would run:

uvx ha-mcp

Results by platform

Linux

MCP handshake failed2026-11-09 · probed over pypi

5 recorded runs, oldest first.

handshake failed: MCP error -32000: Connection closed
--- stderr (tail) ---
Downloading beartype (1.5MiB)
Downloading pydantic-monty (8.8MiB)
Downloading ha-mcp (3.9MiB)
 Downloaded beartype
 Downloaded ha-mcp
 Downloaded pydantic-monty
Installed 71 packages in 63ms

==============================================================================
                    Home Assistant MCP Server - Configuration Error
==============================================================================

Missing required environment variables:
  - HOMEASSISTANT_URL
  - HOMEASSISTANT_TOKEN

To fix this, you need to provide your Home Assistant connection details:

  1. HOMEASSISTANT_URL - Your Home Assistant instance URL
     Example: http://homeassistant.local:8123

  2. HOMEASSISTANT_TOKEN - A long-lived access token (an administrator's is recommended)
     Get one from: Home Assistant -> Profile -> Long-Lived Access Tokens

Configuration options:
  - Set environment variables directly:
      export HOMEASSISTANT_URL=http://homeassistant.local:8123
      export HOMEASSISTANT_TOKEN=your_token_here

  - Or create a .env file in the project directory (copy from .env.example)

For detailed setup instructions, see:
  https://github.com/homeassistant-ai/ha-mcp#-installation

==============================================================================

macOS

timed out2026-11-09 · probed over pypi

5 recorded runs, oldest first.

handshake failed: MCP error -32001: Request timed out
--- stderr (tail) ---
Downloading beartype (1.5MiB)
Downloading ha-mcp (3.9MiB)
 Downloaded beartype
   Building pydantic-monty==0.0.18
 Downloaded ha-mcp

Windows

MCP handshake failed2026-11-09 · probed over pypi

5 recorded runs, oldest first.

handshake failed: MCP error -32000: Connection closed
--- stderr (tail) ---
Downloading beartype (1.5MiB)
Downloading pywin32 (6.6MiB)
Downloading ha-mcp (3.9MiB)
Downloading pydantic-monty (9.0MiB)
Downloading pydantic-core (2.2MiB)
 Downloaded pydantic-core
 Downloaded pydantic-monty
 Downloaded beartype
 Downloaded pywin32
 Downloaded ha-mcp
Installed 71 packages in 9.80s

==============================================================================
                    Home Assistant MCP Server - Configuration Error
==============================================================================

Missing required environment variables:
  - HOMEASSISTANT_URL
  - HOMEASSISTANT_TOKEN

To fix this, you need to provide your Home Assistant connection details:

  1. HOMEASSISTANT_URL - Your Home Assistant instance URL
     Example: http://homeassistant.local:8123

  2. HOMEASSISTANT_TOKEN - A long-lived access token (an administrator's is recommended)
     Get one from: Home Assistant -> Profile -> Long-Lived Access Tokens

Configuration options:
  - Set environment variables directly:
      export HOMEASSISTANT_URL=http://homeassistant.local:8123
      export HOMEASSISTANT_TOKEN=your_token_here

  - Or create a .env file in the project directory (copy from .env.example)

For detailed setup instructions, see:
  https://github.com/homeassistant-ai/ha-mcp#-installation

==============================================================================

Badge

Paste this into the project README to show the current result:

[![does it install](https://img.shields.io/endpoint?url=https://doesitinstall.com/badge/io.github.homeassistant-ai__ha-mcp.json)](https://doesitinstall.com/s/io.github.homeassistant-ai__ha-mcp.html)