ha-mcp 是一个基于 Model Context Protocol（MCP）构建的 Home Assistant 服务端，用于让大语言模型客户端接入智能家居系统。测试环境为 Windows 11 专业版 24H2、Python 3.13.14，通过 PyPI 安装 ha-mcp 8.7.0 跑通了基础环境与协议握手。
ha-mcp 是用 Python 编写的 Home Assistant MCP 服务端工具。大语言模型客户端与智能家居使用者可以通过该工具接入 Home Assistant 接口，向模型暴露 77 个控制与查询工具以处理自动化指令。
主要功能
该服务向 MCP 客户端暴露 Home Assistant 的操作接口。在协议层面，它注册并导出了 77 个工具，包含 ha_get_app、ha_manage_app、ha_list_floors_areas、ha_manage_blueprints 以及 ha_report_issue 等。底层依赖 fastmcp、mcp、pydantic、httpx 与 websockets 等库处理通信与数据校验。
安装与依赖
测试在隔离的虚拟环境中执行安装。执行命令如下：
python -m venv venv && venv\Scripts\python.exe -m pip install ha-mcp==8.7.0安装过程耗时 7 分 08 秒。安装完成后，pip 缓存体积从 0 增加到 145MB。venv/Scripts 目录下生成了 5 个可执行入口：ha-mcp、ha-mcp-web、ha-mcp-oidc、ha-mcp-oauth 和 ha-mcp-smoke-test。
最短能跑通的用法
安装完成后，可先运行自带的自检程序验证依赖完整性：
venv\Scripts\ha-mcp-smoke-test.exe自检程序运行后输出 SMOKE TEST PASSED，确认 fastmcp、mcp、pydantic、httpx、websockets 等 9 个关键库导入成功，Server 成功实例化并扫描到 77 个工具。
随后验证进程的标准输入输出交互。向 ha-mcp.exe 的 stdin 依次写入 initialize（protocolVersion=2024-11-05）与 tools/list 请求，即可完成协议初始化并获取工具清单。
关键参数
运行 ha-mcp 服务端需要两个基础环境变量：
HOMEASSISTANT_URL：指向 Home Assistant 实例的访问地址。HOMEASSISTANT_TOKEN：用于访问 Home Assistant 的长期访问令牌。
结果在哪里看
进程通信走标准输入输出。向进程写入 initialize 握手指令后，终端返回协议头信息，显示 serverInfo=ha-mcp v8.7.0 与 protocolVersion=2024-11-05。写入 tools/list 指令后，标准输出会返回结构化的 JSON 数据，列出包括 ha_get_app 在内的全部 77 个工具定义。
实际使用中的坑
在没有配置环境变量的情况下，执行参数查询命令：
venv\Scripts\ha-mcp.exe --help控制台不会输出任何帮助信息。程序在解析命令行参数前直接检测环境变量，因为缺少 HOMEASSISTANT_URL 与 HOMEASSISTANT_TOKEN，直接打印 Configuration Error 并退出。如需查看参数或正常调用，必须先设置好这两个环境变量。
这次测试只验证到协议层：包能装、进程能起、initialize 与 tools/list 正常返回 77 个工具。由于没有接入真实 Home Assistant 实例，所有需要读实体状态、调用服务的工具都没有实际执行过；接真实实例时是否出现认证或 WebSocket 重连问题，这次没验证。
适合谁
适合需要在本地环境将大模型（如 Claude 或支持 MCP 的客户端）接入 Home Assistant 的开发者。使用前需要本地具备 Python 3.13 以上环境，并准备好可用的 Home Assistant 访问地址与令牌。
