适合谁
- 希望用 AI 配置和维护 Home Assistant 的用户
- 需要自动化调试、历史查询和系统管理能力的 Home Assistant 用户
- 使用 Home Assistant OS、Supervised、Container 或 Core 的用户
H
63FMRS · C
非官方、社区维护的 Home Assistant MCP 服务器，功能覆盖设备控制、配置管理、调试和系统维护。能力全面但写入权限较高；建议从自定义组件开始，并谨慎启用文件和 YAML 测试版工具。
HA-MCP 是一个综合性的 Model Context Protocol 服务器，让 AI 助手通过自然语言与 Home Assistant 交互。它支持智能家居设备控制、状态查询、服务调用，以及自动化、脚本、场景、仪表板、辅助实体、区域、备份和调试等管理任务。项目由社区维护，采用 MIT 许可证。
工具能力
ha_get_addon
获取 Home Assistant 应用或附加组件信息。
ha_manage_addon
管理 Home Assistant 应用或附加组件。
ha_list_floors_areas
列出楼层和区域。
ha_remove_area_or_floor
删除区域或楼层。
ha_set_area_or_floor
创建或更新区域或楼层。
ha_manage_pipeline
管理 Assist 流程。
ha_config_get_automation
读取自动化配置。
ha_config_remove_automation
删除自动化。
ha_config_set_automation
创建或更新自动化。
ha_get_blueprint
获取蓝图。
ha_import_blueprint
导入蓝图。
ha_config_get_calendar_events
获取日历事件。
ha_config_remove_calendar_event
删除日历事件。
ha_config_set_calendar_event
创建或更新日历事件。
ha_get_camera_image
获取摄像头图像。
ha_get_dashboard_screenshot
获取仪表板截图；测试版。
ha_config_delete_dashboard_resource
删除仪表板资源。
ha_config_delete_dashboard
删除仪表板。
ha_config_get_dashboard
读取仪表板配置。
ha_config_list_dashboard_resources
列出仪表板资源。
ha_config_set_dashboard_resource
创建或更新仪表板资源。
ha_config_set_dashboard
创建或更新仪表板。
ha_dev_manage_server
管理 Home Assistant 服务器开发设置。
ha_dev_manage_settings
管理开发设置。
ha_get_device
获取设备信息。
ha_remove_device
删除设备。
ha_set_device
创建或更新设备信息。
ha_manage_energy_prefs
管理能源偏好设置。
ha_get_entity_exposure
获取实体暴露设置。
ha_get_entity
获取实体注册信息。
ha_remove_entity
删除实体注册信息。
ha_set_entity
创建或更新实体注册信息。
ha_delete_file
删除允许路径中的文件；测试版。
ha_list_files
列出允许目录中的文件；测试版。
ha_read_file
读取允许路径中的文件；测试版。
ha_write_file
写入允许目录中的文件；测试版。
ha_config_list_groups
列出组。
ha_config_remove_group
删除组。
ha_config_set_group
创建或更新组。
ha_get_hacs_info
获取 HACS 信息。
ha_manage_hacs
管理 HACS。
ha_config_list_helpers
列出辅助实体。
ha_config_set_helper
创建或更新辅助实体。
ha_remove_helpers_integrations
删除辅助实体集成。
ha_get_automation_traces
获取自动化执行轨迹。
ha_get_history
获取历史记录。
ha_get_logs
获取日志。
ha_get_integration
获取集成信息。
ha_get_system_health
获取系统健康信息。
ha_set_integration
更新集成设置。
ha_config_get_category
获取类别。
ha_config_get_label
获取标签。
ha_config_remove_category
删除类别。
ha_config_remove_label
删除标签。
ha_config_set_category
创建或更新类别。
ha_config_set_label
创建或更新标签。
ha_manage_radio
管理 Matter 或其他相关无线电设置。
ha_config_get_scene
读取场景配置。
ha_config_remove_scene
删除场景。
ha_config_set_scene
创建或更新场景。
ha_config_get_script
读取脚本配置。
ha_config_remove_script
删除脚本。
ha_config_set_script
创建或更新脚本。
ha_get_overview
获取 Home Assistant 概览。
ha_get_state
获取实体状态。
ha_search
搜索实体和配置。
ha_bulk_control
批量控制设备。
ha_call_event
调用事件。
ha_call_service
调用 Home Assistant 服务。
ha_get_operation_status
获取操作状态。
ha_list_services
列出服务。
ha_config_get_yaml
读取 YAML 配置；测试版。
ha_config_set_yaml
安全地添加、替换或删除顶层 YAML 配置；测试版。
ha_manage_backup
管理备份。
ha_manage_custom_tool
管理自定义工具；测试版。
ha_manage_theme
管理主题。
ha_manage_updates
管理更新。
ha_reload_core
重新加载核心。
ha_restart
重启 Home Assistant。
ha_get_todo
获取待办列表。
ha_remove_todo_item
删除待办事项。
ha_set_todo_item
创建或更新待办事项。
ha_eval_template
执行模板评估。
ha_report_issue
提交问题报告。
ha_get_zone
获取区域信息。
ha_remove_zone
删除区域。
ha_set_zone
创建或更新区域。
安装接入
首选方式是在 Home Assistant 中通过 HACS 安装 HA-MCP Custom Component，重启 Home Assistant，添加 HA-MCP Server 集成，然后从 Configure 页面复制连接 URL 并粘贴到 AI 客户端。也可使用 Home Assistant 应用/附加组件、Docker 或 PyPI/uvx。每个客户端只应配置一种安装方式。文件和 YAML 工具需要额外安装 HA-MCP File & YAML Tools 条目，并启用相应测试版功能开关。
选型与风险
不适合谁
- 只需要语音式控制已暴露设备、且不需要配置管理的用户
- 不使用 Home Assistant 的用户
- 需要将服务器视为 Home Assistant 官方产品的用户
所需权限
- 需要访问 Home Assistant API 及其实体、服务和配置能力
- 控制、配置修改、删除、重启和备份等操作可能需要较高权限
- 文件和 YAML 工具需要安装自定义组件并启用测试版功能开关
- 可启用只读模式、逐工具开关和工具安全策略
风险与副作用
- 写入、删除、重启、备份恢复和 YAML 编辑可能改变或中断智能家居配置
- 文件和 YAML 工具默认关闭，启用后应限制允许路径并保留备份
- stdio 传输存在已知连接问题，生产环境更适合自定义组件或 HTTP 方式
- 同一客户端配置多个安装入口可能导致连接挂起
常见排障
- 确认客户端只配置了一个 ha-mcp 安装入口
- 切换工具搜索、工具开关或只读模式后刷新或重新连接客户端工具列表
- 检查 Home Assistant 日志或集成 Configure 页面中的连接 URL
- stdio 连接异常时改用自定义组件或 streamable HTTP
- 确认文件和 YAML 工具已安装对应组件并启用 ENABLE_BETA_FEATURES
使用场景
通过自然语言控制智能家居设备和服务
创建或修改自动化、脚本、场景和仪表板
查询实体状态、历史记录、日志和自动化轨迹
管理辅助实体、区域、标签、组、HACS、备份和更新
支持客户端
Claude Desktop完整支持
Claude.ai完整支持
ChatGPT完整支持
Claude Code完整支持
Gemini CLI完整支持
Open WebUI完整支持
VSCode完整支持
Cursor完整支持