ha-mcp

library7.6.0pypypiunverified

ha-mcp provides a Home Assistant MCP server enabling AI agents (like Claude, Cursor) to control Home Assistant devices, read sensors, and execute automations via the Model Context Protocol. The current version 7.6.0 requires Python 3.13+ (up to 3.14). Released regularly, it is the primary tool for integrating Home Assistant with MCP-compatible AI assistants.

devops

pip install ha-mcp

github ↗homepage ↗

INSTALL

IMPORT

SIG · HA-MCP

ha-mcp

devopspythonv7.6.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MCPServer

✓ from ha_mcp import MCPServer

✗ from ha_mcp.server import MCPServer

MCPServer is re-exported at top-level; direct import from submodule may break in future.

Minimal async server setup. Set HA_BASE_URL and HA_ACCESS_TOKEN environment variables.

import os from ha_mcp import MCPServer async def main(): server = MCPServer( base_url=os.environ.get("HA_BASE_URL", "http://homeassistant.local:8123"), token=os.environ.get("HA_ACCESS_TOKEN", ""), ha_version="auto" ) await server.run() if __name__ == "__main__": import asyncio asyncio.run(main())

Debug

Known issues

breakingRequires Python 3.13+ (up to 3.13, <3.14). Python 3.12 or lower will fail installation.

fix

Upgrade to Python 3.13+ or use an older ha-mcp version (though not recommended).

affects: <7.6.0

gotchaThe ha_version parameter defaults to 'auto', which queries Home Assistant version on connect. If your HA version is old or connection fails, you must set it explicitly (e.g., '2024.1.0').

fix

Set ha_version to your Home Assistant version string if auto-detection fails.

affects: all

deprecatedThe old entry point ha_mcp:main is deprecated; use the MCPServer class API instead.

fix

Migrate to from ha_mcp import MCPServer and run server with MCPServer(...).run().

affects: >=6.0.0

gotchaEnvironment variable HA_HOST is not used. Use HA_BASE_URL (full URL, including scheme).

fix

Set HA_BASE_URL instead of HA_HOST.

affects: >=7.0.0

Upgrade

Version history

7.6.0latest on PyPI · released May 27, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/homeassistant-ai/ha-mcp ↗

homepagehttps://github.com/homeassistant-ai/ha-mcp ↗