ha-mcp
ha-mcp 是一款非官方但功能强大的 Home Assistant MCP（模型上下文协议）服务器，旨在搭建人工智能与智能家居之间的桥梁。它允许用户通过自然语言直接与大模型助手（如 Claude）对话，从而轻松控制智能设备、查询实时状态、执行自动化服务以及管理家庭场景，无需编写复杂的代码或指令。
这一工具主要解决了传统智能家居操作中“命令繁琐”与“交互割裂”的痛点。过去，用户往往需要打开特定 App 或记忆精确的服务名称才能操作设备；现在，只需像与人交谈一样发出指令，AI 即可理解意图并调用 Home Assistant 完成操作，极大地提升了智能家居的易用性和响应速度。
ha-mcp 非常适合两类人群：一是希望提升生活便利性的普通智能家居用户，让他们能用最直观的方式管理家庭设备；二是开发者与技术爱好者，可借此探索 AI Agent 在物联网领域的实际应用。其技术亮点在于基于 FastMCP 构建，拥有超过 88 种预置工具函数，支持 OAuth 安全认证，并提供了针对 macOS 和 Windows 的一键安装脚本，让用户能在几分钟内快速完成部署并连接至自己的 Home Assistant 环境。
使用场景
独居的开发者李明正在深夜赶工，突然想起出门时忘记关闭客厅的取暖器，且担心家中宠物是否安全，急需远程确认并调整家居状态。
没有 ha-mcp 时
- 操作繁琐割裂：必须停下代码编写，手动解锁手机，打开 Home Assistant APP，层层点击菜单才能找到对应开关。
- 状态查询困难：无法直接通过自然语言询问“客厅温度多少”或“宠物摄像头在线吗”，需肉眼在仪表盘上逐个查找传感器数据。
- 自动化门槛高：若想临时创建一条“温度过高自动关暖气”的规则，需要进入复杂的后台配置界面编写 YAML 或调试可视化编辑器。
- 多设备协同差：同时控制灯光、窗帘和暖通设备时，需在多个页面间反复切换，难以实现一键式的场景联动。
- 打断心流严重：频繁在开发环境与智能家居控制之间切换注意力，导致编程思路中断，工作效率大幅降低。
使用 ha-mcp 后
- 语音即控：直接在 Claude Desktop 中输入“关闭客厅取暖器并打开走廊灯”，ha-mcp 立即解析意图并调用服务执行，全程无需离开代码编辑器。
- 自然语言查询：随口问“现在客厅温度和湿度是多少？”，ha-mcp 实时读取传感器状态并用通俗语言反馈，信息获取零延迟。
- 动态自动化生成：指令“如果客厅温度超过 26 度就自动关暖气”，ha-mcp 自动构建并部署相应的自动化脚本，无需手动配置底层逻辑。
- 复杂场景一键触发：一句“我准备睡觉了”，ha-mcp 即可协调关闭所有非必要电器、拉上窗帘并开启安防模式，实现多设备无缝联动。
- 专注力零损耗：所有家居交互融入对话流中，开发者无需切换上下文，保持了深度的工作心流状态。
ha-mcp 将原本割裂的智能家居控制转化为自然的对话交互，让 AI 助手真正成为连接人与物理世界的智能中枢。
运行环境要求
- macOS
- Windows
- Linux
未说明
未说明
快速开始
⚠️ OAuth 模式中的重大变更（v7.0.0） — 请在服务器端设置
HOMEASSISTANT_URL。同意表单现在仅接受令牌。迁移指南 →
非官方且强大的 Home Assistant MCP 服务器
一个全面的模型上下文协议（MCP）服务器，使 AI 助手能够与 Home Assistant 交互。
使用自然语言控制智能家居设备、查询状态、执行服务并管理您的自动化。
🚀 开始使用
完整指南，帮助您快速上手 Claude Desktop（约10分钟）
无需付费订阅。 点击您的操作系统：
快速安装（约5分钟）
🍎 macOS
- 前往 claude.ai 并登录（或创建免费账户）
- 打开 终端 并运行：
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh - 下载 Claude Desktop（或重启：Claude 菜单 → 退出）
- 向 Claude 提问：“你能看到我的 Home Assistant 吗？”
现在您已连接到演示环境！连接您自己的 Home Assistant →
🪟 Windows
- 前往 claude.ai 并登录（或创建免费账户）
- 打开 Windows PowerShell（从开始菜单）并运行：
irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex - 下载 Claude Desktop（或重启：文件 → 退出）
- 向 Claude 提问：“你能看到我的 Home Assistant 吗？”
现在您已连接到演示环境！连接您自己的 Home Assistant →
🏠 Home Assistant OS（附加组件）
将仓库添加到您的 Home Assistant 实例：
从附加组件商店安装 “Home Assistant MCP 服务器”，等待安装完成
点击 启动，然后打开 日志 选项卡以找到您的唯一 MCP URL
使用该 URL 配置您的 AI 客户端
无需设置令牌或凭据——该附加组件会自动连接到 Home Assistant。
🧙 适用于15+客户的设置向导
Claude Code、Gemini CLI、ChatGPT、Open WebUI、VSCode、Cursor 等。
遇到问题？请查看 常见问题解答与故障排除
💬 您能用它做什么？
只需用自然语言与 Claude 对话即可。以下是一些实际案例：
| 您说 | 发生什么 |
|---|---|
| "创建一个日落时开启门廊灯的自动化" | 创建具有正确触发器和动作的自动化 |
| "在我的仪表板上添加一个天气卡片" | 更新您的 Lovelace 仪表板，添加新卡片 |
| "运动传感器自动化不起作用，请调试一下" | 分析执行轨迹，找出问题并提出修复建议 |
| "让我的早晨例行自动化也打开咖啡机" | 读取现有自动化，添加新动作并更新 |
| "创建一个脚本，设置电影模式：调暗灯光、拉上百叶窗、打开电视" | 创建包含一系列动作的可重用脚本 |
花更少的时间配置，更多的时间享受您的智能家居生活。
✨ 功能
| 类别 | 功能 |
|---|---|
| 🔍 搜索 | 模糊实体搜索、深度配置搜索、系统概览 |
| 🏠 控制 | 任意服务、批量设备控制、实时状态 |
| 🔧 管理 | 自动化、脚本、辅助实体、仪表板、区域、分区、组、日历、蓝图 |
| 📊 监控 | 历史记录、统计信息、摄像头快照、自动化轨迹、ZHA 设备 |
| 💾 系统 | 备份/恢复、更新、附加组件、设备注册表 |
完整工具列表（88 个工具）
| 类别 | 工具 |
|---|---|
| 附加组件 | ha_call_addon_api, ha_get_addon |
| 区域与楼层 | ha_config_list_areas, ha_config_list_floors, ha_config_remove_area, ha_config_remove_floor, ha_config_set_area, ha_config_set_floor |
| 自动化 | 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_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_dashboard_find_card |
| 设备注册表 | ha_get_device, ha_remove_device, ha_update_device |
| 实体注册表 | 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 |
| HACS | ha_hacs_add_repository, ha_hacs_download, ha_hacs_repository_info, ha_hacs_search |
| 辅助实体 | ha_config_list_helpers, ha_config_remove_helper, ha_config_set_helper, ha_get_helper_schema, ha_set_config_entry_helper |
| 历史与统计 | ha_get_automation_traces, ha_get_history, ha_get_logs, ha_get_statistics |
| 集成 | ha_delete_config_entry, ha_get_integration, ha_set_integration_enabled |
| 标签与分类 | 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_config_get_script, ha_config_remove_script, ha_config_set_script |
| 搜索与发现 | ha_deep_search, ha_get_overview, ha_get_state, ha_search_entities |
| 服务与设备控制 | ha_bulk_control, ha_call_service, ha_get_operation_status, ha_list_services |
| 系统 | ha_backup_create, ha_backup_restore, ha_check_config, ha_config_set_yaml, ha_get_system_health, ha_get_updates, ha_reload_core, ha_restart |
| 待办事项 | ha_get_todo, ha_remove_todo_item, ha_set_todo_item |
| 实用工具 | ha_eval_template, ha_install_mcp_tools, ha_report_issue |
| 分区 | ha_get_zone, ha_remove_zone, ha_set_zone |
🔌 自定义组件 (ha_mcp_tools)
部分工具需要在 Home Assistant 中安装配套的自定义组件。标准 HA API 并不提供对文件系统的访问或 YAML 配置的编辑功能，而该组件则同时提供了这两项能力。
需要该组件的工具：
| 工具 | 描述 |
|---|---|
ha_config_set_yaml |
安全地在 configuration.yaml 和包文件中添加、替换或移除顶级 YAML 键（自动备份、验证和配置检查） |
ha_list_files |
列出允许目录中的文件（www/、themes/、custom_templates/） |
ha_read_file |
从允许路径读取文件（配置 YAML、日志、www/、themes/、custom_templates/、custom_components/） |
ha_write_file |
将文件写入允许目录 |
ha_delete_file |
删除允许目录中的文件 |
其他所有工具无需该组件即可正常工作。这五个工具若缺少该组件，则会返回错误并附上安装说明。
这些工具还需要启用以下功能标志：HAMCP_ENABLE_FILESYSTEM_TOOLS=true（文件工具）和 ENABLE_YAML_CONFIG_EDITING=true（YAML 编辑）。要启用安装工具 ha_install_mcp_tools，请设置 HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true。
使用 HACS 安装（推荐）
手动添加方法：打开 HACS > 集成 > 三点菜单 > 自定义仓库 > 添加 https://github.com/homeassistant-ai/ha-mcp（类别：集成）> 下载。
安装完成后，请重启 Home Assistant。然后打开 设置 > 设备与服务 > 添加集成，搜索 HA MCP Tools。
手动安装
将此仓库中的 custom_components/ha_mcp_tools/ 文件夹复制到你的 HA 的 config/custom_components/ 目录下。重启 Home Assistant 后，按照上述步骤添加集成。
🧠 使用智能体技能获得更佳效果
该服务器为你的 AI 智能体提供了控制 Home Assistant 的工具。为了获得更好的配置效果，建议将其与 Home Assistant 智能体技能 结合使用——这些领域知识能够教会智能体 Home Assistant 的最佳实践。
MCP 服务器可以创建自动化、辅助实体和仪表板，但它并不知道如何合理地组织它们。如果没有领域知识，智能体会倾向于过度依赖模板，选择错误类型的辅助实体，或者生成难以维护的自动化流程。而这些技能则填补了这一空白：它们提倡使用原生构建而非 Jinja2 替代方案，帮助正确选择辅助实体类型，提供安全的重构流程，并指导如何恰当地使用自动化模式。
内置技能集
来自 homeassistant-ai/skills 的技能被打包并作为 MCP 资源 通过 skill:// URI 提供。任何支持资源的 MCP 客户端都可以自动发现这些技能，无需手动安装。
| 设置 | 默认值 | 描述 |
|---|---|---|
ENABLE_SKILLS |
true |
将技能作为 MCP 资源提供。资源不会自动注入上下文——客户端必须显式请求才能获取。 |
ENABLE_SKILLS_AS_TOOLS |
true |
通过 list_resources/read_resource 工具公开技能和文档资源。支持资源的客户端可以将其设置为 false，以减少工具数量。 |
对于希望使用本地技能文件的客户端，仍可手动安装技能——具体操作请参阅 skills 仓库。
🧪 开发通道
想要提前体验新功能和修复吗？每当有代码推送到主分支时，都会发布开发版本（.devN）。
开发通道文档 — 包括 pip/uvx、Docker 和 Home Assistant 插件的使用说明。
🤝 贡献
有关开发环境搭建、测试说明及贡献指南，请参阅 CONTRIBUTING.md。
如需全面的测试文档，请查看 tests/README.md。
🔒 隐私
Ha-mcp 在您的设备上本地运行。您的智能家居数据将始终保留在您的网络中。
- 可配置的遥测功能 — 可选的匿名使用统计
- 不收集个人数据 — 我们绝不会收集实体名称、配置或设备数据
- 用户可控的错误报告 — 仅在您明确同意的情况下才会发送
更多详细信息，请参阅我们的 隐私政策。
📄 许可证
本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。
🙏 致谢
- Home Assistant：令人惊叹的智能家居平台 (!)
- FastMCP：优秀的 MCP 服务器框架
- Model Context Protocol：标准化的 AI 应用程序通信协议
- Claude Code：由 AI 驱动的编码助手
👥 贡献者
维护者
- @julienld — 项目创建者及核心维护者。
- @sergeykad — 核心维护者。
- @kingpanther13 — 核心维护者。
贡献者
- @bigeric08 — 明确添加
mcp依赖，以支持 2025-11-25 版本协议。 - @airlabno — 支持计划时间块中的
data字段。 - @ryphez — 提供 Codex 桌面 UI 的 MCP 快速设置指南。
- @Danm72 — 提供实体注册表工具（
ha_set_entity、ha_get_entity），用于管理实体属性。 - @Raygooo — 支持 SOCKS 代理。
- @cj-elevate — 提供集成与实体管理工具（启用/禁用/删除）；以及人员/区域/标签配置存储路由功能。
- @maxperron — 参与 Beta 测试。
- @kingbear2 — 提供 Windows UV 设置指南。
- @konradwalsh — 通过 GitHub Sponsors 提供资金支持。感谢！☕
- @knowald — 在
ha_get_system_overview中，通过设备注册表解析区域信息，适用于通过父设备分配的实体。 - @zorrobyte — 在 OAuth 模式下为每个客户端提供 WebSocket 凭证，修复了 WebSocket 工具失败的问题。
- @deanbenson — 修复了大型 Home Assistant 实例中，包含大量自动化时
ha_deep_search超时的问题。 - @saphid — 提供配置条目选项流程工具（初始设计，#590）。
- @adraguidev — 修复基于菜单的组助手配置流程问题（#647）。
- @transportrefer — 提供集成选项检查功能（支持
ha_get_integration模式，#689）。 - @teh-hippo — 修复蓝图导入时缺少保存步骤的问题。
- @smenzer — 修正文档内容。
- @The-Greg-O — 提供用于删除配置条目的 REST API。
- @restriction — 负责任地披露：python_transform 沙箱缺少调用目标验证。
- @lcrostarosa — 提出诊断和健康监测工具的概念（#675），启发了系统/错误日志、维修以及 ZHA 无线电指标的集成。
💬 社区
- GitHub 讨论区 — 提问、分享想法
- 问题追踪器 — 报告 bug、请求功能或建议改进工具行为
⭐ 星标历史
版本历史
v7.2.0.dev3382026/04/07v7.2.0.dev3372026/04/07v7.2.0.dev3362026/04/07v7.2.0.dev3352026/04/07v7.2.0.dev3342026/04/07v7.2.02026/04/01v7.1.02026/03/18v7.0.02026/03/11v6.7.22026/03/04v6.7.12026/02/20v6.7.02026/02/17v6.6.12026/02/10v6.6.02026/02/10v6.5.02026/02/03v6.4.02026/01/27v6.3.12026/01/20v6.3.02026/01/17v6.2.02026/01/12v6.0.02026/01/07v5.1.02026/01/07相似工具推荐
openclaw
OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。 这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。 OpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你
stable-diffusion-webui
stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。 无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。
everything-claude-code
everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。 通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。 这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上
ComfyUI
ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。 这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。 无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。
markitdown
MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。 在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。 这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器
LLMs-from-scratch
LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。 该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。 LLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备