使用说明
非官方和真棒家庭助理MCP服务器
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with Home Assistant.
Using natural language, control smart home devices, query states, execute services and manage your automations.
🚀 开始使用
开始使用Claude Desktop的完整指南（约10分钟）
无需付费订阅。 点击您的操作系统：
快速安装（约5分钟）
🍎 macOS
- 首选 claude.ai 登录（或创建免费帐户）
- 打开 终端 并运行：
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh - 下载克劳德桌面 （或重新启动：克劳德菜单→ Quit)
- 问克劳德： “你能看到我的家庭助理吗？”
您现在已连接到演示环境！ 连接您自己的家庭助理→
🪟 Windows
- 首选 claude.ai 登录（或创建免费帐户）
- 打开 Windows PowerShell （从“开始”菜单）并运行：
irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex - 下载克劳德桌面 （或重新启动：文件→ Exit)
- 问克劳德： “你能看到我的家庭助理吗？”
您现在已连接到演示环境！ 连接您自己的家庭助理→
🧙 15个以上客户端的安装向导
Claude Code、Gemini CLI、ChatGPT、Open WebUI、VSCode、Cursor等。
有问题吗？检查 常见问题解答和故障排除
💬 你能用它做什么？
自然地和克劳德谈谈。以下是一些真实的例子：
| 你说 | 发生了什么 |
|---|---|
| “创建一个在日落时打开门廊灯的自动化系统” | 通过适当的触发器和操作创建自动化 |
| “将天气卡添加到我的仪表板” | 用新卡更新Lovelace仪表板 |
| “运动传感器自动化不起作用，请进行调试” | 分析执行跟踪，识别问题，提出修复建议 |
| “让我早上的日常自动化也打开咖啡机” | 读取现有自动化，添加新操作，更新它 |
| 创建一个设置电影模式的脚本：调暗灯光、关闭百叶窗、打开电视 | 创建具有操作序列的可重用脚本 |
花更少的时间配置，更多的时间享受智能家居。
✨ 特性
| 类别 | 功能 |
|---|---|
| 🔍 搜索 | 模糊实体搜索、深度配置搜索、系统概述 |
| 🏠 控制 | 任何服务、批量设备控制、实时状态 |
| 🔧 管理 | 自动化、脚本、助手、仪表板、区域、分区、组、日历、蓝图 |
| 📊 监视器 | 历史、统计、相机快照、自动化跟踪、ZHA设备 |
| 💾 系统 | 备份/还原、更新、附加组件、设备注册表 |
🛠️ Complete Tool List (97 tools)
| 类别 | 工具 |
|---|---|
| 搜索与发现 | ha_search_entities, ha_deep_search, ha_get_overview, ha_get_state |
| 服务和设备控制 | ha_call_service, ha_bulk_control, ha_get_operation_status, ha_get_bulk_status, ha_list_services |
| 自动化 | ha_config_get_automation, ha_config_set_automation, ha_config_remove_automation |
| 脚本 | ha_config_get_script, ha_config_set_script, ha_config_remove_script |
| 帮助实体 | ha_config_list_helpers, ha_config_set_helper, ha_config_remove_helper |
| 仪表盘 | ha_config_get_dashboard, ha_config_set_dashboard, ha_config_update_dashboard_metadata, ha_config_delete_dashboard, ha_get_dashboard_guide, ha_get_card_types, ha_get_card_documentation |
| 面积和楼层 | ha_config_list_areas, ha_config_set_area, ha_config_remove_area, ha_config_list_floors, ha_config_set_floor, ha_config_remove_floor |
| 标签 | ha_config_get_label, ha_config_set_label, ha_config_remove_label, ha_manage_entity_labels |
| 区域 | ha_get_zone, ha_create_zone, ha_update_zone, ha_delete_zone |
| 群组 | ha_config_list_groups, ha_config_set_group, ha_config_remove_group |
| 待办事项 | ha_get_todo, ha_add_todo_item, ha_update_todo_item, ha_remove_todo_item |
| 日历 | ha_config_get_calendar_events, ha_config_set_calendar_event, ha_config_remove_calendar_event |
| 蓝图 | ha_list_blueprints, ha_get_blueprint, ha_import_blueprint |
| 设备注册表 | ha_get_device, ha_update_device, ha_remove_device, ha_rename_entity |
| ZHA与整合 | ha_get_zha_devices, ha_get_entity_integration_source |
| 附加组件 | ha_get_addon |
| 相机 | ha_get_camera_image |
| 历史与统计 | ha_get_history, ha_get_statistics |
| 自动化跟踪 | ha_get_automation_traces |
| 系统和更新 | ha_check_config, ha_restart, ha_reload_core, ha_get_system_info, ha_get_system_health, ha_get_updates |
| 备份与恢复 | ha_backup_create, ha_backup_restore |
| 效用 | ha_get_logbook, ha_eval_template, ha_get_domain_docs, ha_get_integration |
🧠 通过代理技能获得更好的结果
此服务器为您的AI代理工具提供了控制家庭助理的功能。为了获得更好的配置，请将其与 家庭助理代理技能 --指导代理Home Assistant最佳实践的领域知识。
MCP服务器可以创建自动化、助手和仪表板，但它对以下内容没有意见 如何 以构建它们。如果没有领域知识，代理往往会过度依赖模板，选择错误的助手类型，或者产生难以维护的自动化。这些技能填补了这一空白：Jinja2变通方法的原生构造、正确的帮助者选择、安全的重构工作流程以及正确使用自动化模式。
🧪 开发者频道
想要尽早访问新功能和修复程序？开发人员发布(.devN)每次向master推送都会发布。
开发渠道文档 --pip/uvx、Docker和Home Assistant插件的说明。
🤝 贡献
有关开发设置、测试说明和贡献指南，请参阅 贡献.md.
有关全面的测试文档，请参阅 测试/README.md.
🔒 隐私
哈mcp跑 本地 在你的机器上。您的智能家居数据保留在您的网络上。
- 可配置遥测 --可选匿名使用统计信息
- 不收集个人数据 --我们从不收集实体名称、配置或设备数据
- 用户控制的错误报告 --仅在您明确批准的情况下发送
有关完整详细信息，请参阅我们的 隐私政策.
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
👥 贡献者
- @朱利安 --项目维护者和核心贡献者。
- @王熊2 --Windows UV设置指南。
- @塞尔维亚 --仪表板卡片级CRUD操作，更好的变更日志，并消除了对textdistance/numpy的依赖。
- @康拉德沃尔什 --财政支持通过 GitHub赞助商非常感谢。 ☕
- @cj提升 --集成和实体管理工具（启用/禁用/删除）。
- @国王13 --开发渠道文档、批量控制验证、OAuth 2.1文档、工具整合、错误处理改进和本机解决方案指南。
- @丹麦72 --实体注册表工具(
ha_set_entity,ha_get_entity)用于管理实体属性。 - @Raygooo --SOCKS代理支持。
