Home Assistant MCP | English Version
- 通过 MCP 协议与 Home Assistant 集成，获取设备上下文并进行控制（开关、灯光亮度）。
- 自动获取/创建长期访问令牌，自动安装/检测
mcp_server集成，开箱即用。 - 提供一个轻量 MCP 服务，封装上游 Home Assistant 的原生工具并提供更易用的接口。
- 开源协议：MIT。可点击切换英文文档：
README_EN.md。
功能特性
- 自动令牌管理：创建名为
mcp的长期令牌并缓存到./.cache/token.txt。 - 集成管理：检测并安装 Home Assistant 的
mcp_server集成。 - 上下文获取：从 Home Assistant 拉取实时设备上下文（YAML），生成稳定
id（设备名 MD5）。 - 设备控制：按
id批量控制开关与灯光亮度。
架构概览
- 上游：Home Assistant 提供的
mcp_server集成暴露 MCP 工具（GetLiveContext、HassTurnOn、HassTurnOff、HassLightSet）。 - 中间层：本项目以 MCP 客户端身份连接上游，并以 MCP 服务身份对外提供简化工具（
get_device_info、switch_control、light_set）。 - 连接方式：
- 到上游 Home Assistant：SSE（
{HOME_ASSISTANT_URL}/mcp_server/sse+Authorization: Bearer <token>）。 - 对下游客户端：默认使用 MCP 标准的进程
stdio运行模式（由fastmcp决定）；SSE 端点由 Home Assistant 集成提供。
- 到上游 Home Assistant：SSE（
系统要求
- Python
>=3.11 - 运行中的 Home Assistant 实例，且可访问其 URL（本地默认
http://127.0.0.1:8123）
安装
- 在项目根目录执行：
pip install .- 或使用 Hatch 构建：
pip install hatch→hatch build→ 安装产物
快速开始
- 配置环境变量（可选，均有默认值）：
HOME_ASSISTANT_USERNAME默认adminHOME_ASSISTANT_PASSWORD默认admin123HOME_ASSISTANT_URL默认http://127.0.0.1:8123HOME_ASSISTANT_CACHE_DIR默认./.cache
- 一键启动：
home-assistant-mcp- 等价于调用
home_assistant_mcp:main，会：- 获取/创建长期令牌
- 确保安装
mcp_server集成 - 作为 MCP 服务运行，并连接到上游 Home Assistant 的 SSE 端点
- 仅做准备（只创建令牌并安装集成）：
python -m home_assistant_mcp.home_assistant_setup
MCP 工具一览（对下游提供）
get_device_info()：强制刷新并返回设备列表（含id、names、areas等）。switch_control(id: List[str], on: bool)：按设备id批量开/关。light_set(id: List[str], brightness: Optional[int])：设置亮度0-100；None表示关闭。
用法示例
- 通过支持进程型 MCP 的客户端运行本服务（例如把命令配置为
home-assistant-mcp）。 - 获取设备：调用
get_device_info，保存返回的id。 - 控制设备：将目标设备
id列表传给switch_control或light_set。
环境变量与缓存
- 令牌文件：
./.cache/token.txt。 - 修改默认目录：通过
HOME_ASSISTANT_CACHE_DIR。 - 令牌来源：优先读取缓存；若不存在则使用
HOME_ASSISTANT_USERNAME/PASSWORD到HOME_ASSISTANT_URL获取。
代码定位
- 入口：
src/home_assistant_mcp/__init__.py:6（main()） - 令牌与集成：
src/home_assistant_mcp/home_assistant_setup.py:18（get_or_create_long_token）、227（同步封装） - 控制器：
src/home_assistant_mcp/mcp_server.py:15（HomeAssistantController） - 工具注册与服务：
src/home_assistant_mcp/mcp_server.py:226（MCPHomeAssistantServer），292（run()） - 项目脚本入口：
pyproject.toml:15-16
故障排查
- 认证错误：删除缓存
./.cache/token.txt后重试；检查用户名/密码与HOME_ASSISTANT_URL。 - SSE 不通：确认 Home Assistant 中已安装并启用
mcp_server集成；查看网络连通性。 - 设备缺失：
get_device_info返回为空或不含目标设备时，检查 Home Assistant 的设备命名与区域。
安全建议
- 不要提交真实令牌到代码仓库；建议使用
.cache/与.gitignore避免泄露。 - 生产环境请使用更强口令与 HTTPS（
wss://WebSocket）。
许可证
- 本项目采用 MIT 许可协议发布。
切换语言
- 英文版文档：
README_EN.md