io.github.homeassistant-ai/ha-mcp

Comprehensive Model Context Protocol server for managing Home Assistant through AI assistants.

io.github.homeassistant-ai/ha-mcp · Repository · version 8.2.0 · 4.4k 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-08-16 · probed over pypi

2 recorded runs, oldest first.

handshake failed: MCP error -32000: Connection closed
--- stderr (tail) ---
Downloading cpython-3.13.15-linux-x86_64-gnu (download) (33.2MiB)
 Downloaded cpython-3.13.15-linux-x86_64-gnu (download)
Downloading pydantic-core (2.0MiB)
Downloading pydantic-monty (8.8MiB)
Downloading ha-mcp (1.7MiB)
 Downloaded pydantic-core
 Downloaded pydantic-monty
 Downloaded ha-mcp
Installed 73 packages in 206ms

==============================================================================
                    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
     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

MCP handshake failed2026-08-16 · probed over pypi

2 recorded runs, oldest first.

handshake failed: MCP error -32000: Connection closed
--- stderr (tail) ---
Downloading ha-mcp (1.7MiB)
Downloading cryptography (3.8MiB)
Downloading beartype (1.3MiB)
Downloading pydantic-monty (8.3MiB)
 Downloaded pydantic-monty
 Downloaded cryptography
 Downloaded ha-mcp
 Downloaded beartype
Installed 71 packages in 232ms

==============================================================================
                    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
     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

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

Windows

MCP handshake failed2026-08-16 · probed over pypi

2 recorded runs, oldest first.

handshake failed: MCP error -32000: Connection closed
--- stderr (tail) ---
Downloading pywin32 (6.6MiB)
Downloading ha-mcp (1.7MiB)
Downloading pydantic-core (2.0MiB)
Downloading pydantic-monty (9.0MiB)
 Downloaded pydantic-core
 Downloaded pydantic-monty
 Downloaded ha-mcp
 Downloaded pywin32
Installed 74 packages in 18.52s

==============================================================================
                    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
     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)