[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-homeassistant-ai--ha-mcp":3,"tool-homeassistant-ai--ha-mcp":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",144730,2,"2026-04-07T23:26:32",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":77,"owner_email":78,"owner_twitter":77,"owner_website":77,"owner_url":79,"languages":80,"stars":110,"forks":111,"last_commit_at":112,"license":113,"difficulty_score":32,"env_os":114,"env_gpu":115,"env_ram":115,"env_deps":116,"category_tags":121,"github_topics":77,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":122,"updated_at":123,"faqs":124,"releases":125},5369,"homeassistant-ai\u002Fha-mcp","ha-mcp","The Unofficial and Awesome Home Assistant MCP Server","ha-mcp 是一款非官方但功能强大的 Home Assistant MCP（模型上下文协议）服务器，旨在搭建人工智能与智能家居之间的桥梁。它允许用户通过自然语言直接与大模型助手（如 Claude）对话，从而轻松控制智能设备、查询实时状态、执行自动化服务以及管理家庭场景，无需编写复杂的代码或指令。\n\n这一工具主要解决了传统智能家居操作中“命令繁琐”与“交互割裂”的痛点。过去，用户往往需要打开特定 App 或记忆精确的服务名称才能操作设备；现在，只需像与人交谈一样发出指令，AI 即可理解意图并调用 Home Assistant 完成操作，极大地提升了智能家居的易用性和响应速度。\n\nha-mcp 非常适合两类人群：一是希望提升生活便利性的普通智能家居用户，让他们能用最直观的方式管理家庭设备；二是开发者与技术爱好者，可借此探索 AI Agent 在物联网领域的实际应用。其技术亮点在于基于 FastMCP 构建，拥有超过 88 种预置工具函数，支持 OAuth 安全认证，并提供了针对 macOS 和 Windows 的一键安装脚本，让用户能在几分钟内快速完成部署并连接至自己的 Home Ass","ha-mcp 是一款非官方但功能强大的 Home Assistant MCP（模型上下文协议）服务器，旨在搭建人工智能与智能家居之间的桥梁。它允许用户通过自然语言直接与大模型助手（如 Claude）对话，从而轻松控制智能设备、查询实时状态、执行自动化服务以及管理家庭场景，无需编写复杂的代码或指令。\n\n这一工具主要解决了传统智能家居操作中“命令繁琐”与“交互割裂”的痛点。过去，用户往往需要打开特定 App 或记忆精确的服务名称才能操作设备；现在，只需像与人交谈一样发出指令，AI 即可理解意图并调用 Home Assistant 完成操作，极大地提升了智能家居的易用性和响应速度。\n\nha-mcp 非常适合两类人群：一是希望提升生活便利性的普通智能家居用户，让他们能用最直观的方式管理家庭设备；二是开发者与技术爱好者，可借此探索 AI Agent 在物联网领域的实际应用。其技术亮点在于基于 FastMCP 构建，拥有超过 88 种预置工具函数，支持 OAuth 安全认证，并提供了针对 macOS 和 Windows 的一键安装脚本，让用户能在几分钟内快速完成部署并连接至自己的 Home Assistant 环境。","> ⚠️ **Breaking change in OAuth mode (v7.0.0)** — Set `HOMEASSISTANT_URL` server-side. The consent form now accepts only the token. [Migration guide →](docs\u002FOAUTH.md#migrating-from-v6x)\n\n\u003Cdiv align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhomeassistant-ai_ha-mcp_readme_2daf00c3e699.png\" alt=\"Home Assistant MCP Server Logo\" width=\"300\"\u002F>\n\n  # The Unofficial and Awesome Home Assistant MCP Server\n\n  \u003C!-- mcp-name: io.github.homeassistant-ai\u002Fha-mcp -->\n\n  \u003Cp align=\"center\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftools-88-blue\" alt=\"95+ Tools\">\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Freleases\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fhomeassistant-ai\u002Fha-mcp\" alt=\"Release\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Factions\u002Fworkflows\u002Fe2e-tests.yml\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Fhomeassistant-ai\u002Fha-mcp\u002Fe2e-tests.yml?branch=master&label=E2E%20Tests\" alt=\"E2E Tests\">\u003C\u002Fa>\n    \u003Ca href=\"LICENSE.md\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fhomeassistant-ai\u002Fha-mcp.svg\" alt=\"License\">\u003C\u002Fa>\n    \u003Cbr>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fcommits\u002Fmaster\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fcommit-activity\u002Fm\u002Fhomeassistant-ai\u002Fha-mcp.svg\" alt=\"Activity\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fjlowin\u002Ffastmcp\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBuilt%20with-FastMCP-purple\" alt=\"Built with FastMCP\">\u003C\u002Fa>\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpython\u002Frequired-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fhomeassistant-ai%2Fha-mcp%2Fmaster%2Fpyproject.toml\" alt=\"Python Version\">\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fsponsors\u002Fjulienld\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitHub_Sponsors-☕-blueviolet\" alt=\"GitHub Sponsors\">\u003C\u002Fa>\n  \u003C\u002Fp>\n\n  \u003Cp align=\"center\">\n    \u003Cem>A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with Home Assistant.\u003Cbr>\n    Using natural language, control smart home devices, query states, execute services and manage your automations.\u003C\u002Fem>\n  \u003C\u002Fp>\n\u003C\u002Fdiv>\n\n---\n\n![Demo with Claude Desktop](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhomeassistant-ai_ha-mcp_readme_6e3832b0f629.webp)\n\n---\n\n## 🚀 Get Started\n\n### Full guide to get you started with Claude Desktop (~10 min)\n\n*No paid subscription required.* Click on your operating system:\n\n\u003Cp>\n\u003Ca href=\"https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Fguide-macos\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSetup_Guide_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white\" alt=\"Setup Guide for macOS\" height=\"120\">\u003C\u002Fa>    \u003Ca href=\"https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Fguide-windows\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSetup_Guide_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white\" alt=\"Setup Guide for Windows\" height=\"120\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n### Quick install (~5 min)\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🍎 macOS\u003C\u002Fb>\u003C\u002Fsummary>\n\n1. Go to [claude.ai](https:\u002F\u002Fclaude.ai) and sign in (or create a free account)\n2. Open **Terminal** and run:\n   ```sh\n   curl -LsSf https:\u002F\u002Fraw.githubusercontent.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fmaster\u002Fscripts\u002Finstall-macos.sh | sh\n   ```\n3. [Download Claude Desktop](https:\u002F\u002Fclaude.ai\u002Fdownload) (or restart: Claude menu → Quit)\n4. Ask Claude: **\"Can you see my Home Assistant?\"**\n\nYou're now connected to the demo environment! [Connect your own Home Assistant →](https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Fguide-macos\u002F#step-6-connect-your-home-assistant)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🪟 Windows\u003C\u002Fb>\u003C\u002Fsummary>\n\n1. Go to [claude.ai](https:\u002F\u002Fclaude.ai) and sign in (or create a free account)\n2. Open **Windows PowerShell** (from Start menu) and run:\n   ```powershell\n   irm https:\u002F\u002Fraw.githubusercontent.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fmaster\u002Fscripts\u002Finstall-windows.ps1 | iex\n   ```\n3. [Download Claude Desktop](https:\u002F\u002Fclaude.ai\u002Fdownload) (or restart: File → Exit)\n4. Ask Claude: **\"Can you see my Home Assistant?\"**\n\nYou're now connected to the demo environment! [Connect your own Home Assistant →](https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Fguide-windows\u002F#step-6-connect-your-home-assistant)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🏠 Home Assistant OS (Add-on)\u003C\u002Fb>\u003C\u002Fsummary>\n\n1. Add the repository to your Home Assistant instance:\n\n   [![Add Repository](https:\u002F\u002Fmy.home-assistant.io\u002Fbadges\u002Fsupervisor_add_addon_repository.svg)](https:\u002F\u002Fmy.home-assistant.io\u002Fredirect\u002Fsupervisor_add_addon_repository\u002F?repository_url=https%3A%2F%2Fgithub.com%2Fhomeassistant-ai%2Fha-mcp)\n\n2. Install **\"Home Assistant MCP Server\"** from the Add-on Store and wait for it to complete\n3. Click **Start**, then open the **Logs** tab to find your unique MCP URL\n4. Configure your AI client with that URL\n\nNo token or credential setup needed — the add-on connects to Home Assistant automatically.\n\n[Full add-on documentation →](homeassistant-addon\u002FDOCS.md)\n\n\u003C\u002Fdetails>\n\n### 🧙 Setup Wizard for 15+ clients\n\n**Claude Code, Gemini CLI, ChatGPT, Open WebUI, VSCode, Cursor, and more.**\n\n\u003Cp>\n\u003Ca href=\"https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Fsetup\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FOpen_Setup_Wizard-4A90D9?style=for-the-badge\" alt=\"Open Setup Wizard\" height=\"40\">\u003C\u002Fa>\n\u003C\u002Fp>\n\nHaving issues? Check the **[FAQ & Troubleshooting](https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Ffaq\u002F)**\n\n---\n\n## 💬 What Can You Do With It?\n\nJust talk to Claude naturally. Here are some real examples:\n\n| You Say | What Happens |\n|---------|--------------|\n| *\"Create an automation that turns on the porch light at sunset\"* | Creates the automation with proper triggers and actions |\n| *\"Add a weather card to my dashboard\"* | Updates your Lovelace dashboard with the new card |\n| *\"The motion sensor automation isn't working, debug it\"* | Analyzes execution traces, identifies the issue, suggests fixes |\n| *\"Make my morning routine automation also turn on the coffee maker\"* | Reads the existing automation, adds the new action, updates it |\n| *\"Create a script that sets movie mode: dim lights, close blinds, turn on TV\"* | Creates a reusable script with the sequence of actions |\n\nSpend less time configuring, more time enjoying your smart home.\n\n---\n\n## ✨ Features\n\n| Category | Capabilities |\n|----------|--------------|\n| **🔍 Search** | Fuzzy entity search, deep config search, system overview |\n| **🏠 Control** | Any service, bulk device control, real-time states |\n| **🔧 Manage** | Automations, scripts, helpers, dashboards, areas, zones, groups, calendars, blueprints |\n| **📊 Monitor** | History, statistics, camera snapshots, automation traces, ZHA devices |\n| **💾 System** | Backup\u002Frestore, updates, add-ons, device registry |\n\n\u003Cdetails>\n\u003C!-- TOOLS_TABLE_START -->\n\n\u003Csummary>\u003Cb>Complete Tool List (88 tools)\u003C\u002Fb>\u003C\u002Fsummary>\n\n| Category | Tools |\n|----------|-------|\n| **Add-ons** | `ha_call_addon_api`, `ha_get_addon` |\n| **Areas & Floors** | `ha_config_list_areas`, `ha_config_list_floors`, `ha_config_remove_area`, `ha_config_remove_floor`, `ha_config_set_area`, `ha_config_set_floor` |\n| **Automations** | `ha_config_get_automation`, `ha_config_remove_automation`, `ha_config_set_automation` |\n| **Blueprints** | `ha_get_blueprint`, `ha_import_blueprint` |\n| **Calendar** | `ha_config_get_calendar_events`, `ha_config_remove_calendar_event`, `ha_config_set_calendar_event` |\n| **Camera** | `ha_get_camera_image` |\n| **Dashboards** | `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` |\n| **Device Registry** | `ha_get_device`, `ha_remove_device`, `ha_update_device` |\n| **Entity Registry** | `ha_get_entity_exposure`, `ha_get_entity`, `ha_remove_entity`, `ha_set_entity` |\n| **Files** | `ha_delete_file`, `ha_list_files`, `ha_read_file`, `ha_write_file` |\n| **Groups** | `ha_config_list_groups`, `ha_config_remove_group`, `ha_config_set_group` |\n| **HACS** | `ha_hacs_add_repository`, `ha_hacs_download`, `ha_hacs_repository_info`, `ha_hacs_search` |\n| **Helper Entities** | `ha_config_list_helpers`, `ha_config_remove_helper`, `ha_config_set_helper`, `ha_get_helper_schema`, `ha_set_config_entry_helper` |\n| **History & Statistics** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logs`, `ha_get_statistics` |\n| **Integrations** | `ha_delete_config_entry`, `ha_get_integration`, `ha_set_integration_enabled` |\n| **Labels & Categories** | `ha_config_get_category`, `ha_config_get_label`, `ha_config_remove_category`, `ha_config_remove_label`, `ha_config_set_category`, `ha_config_set_label` |\n| **Scripts** | `ha_config_get_script`, `ha_config_remove_script`, `ha_config_set_script` |\n| **Search & Discovery** | `ha_deep_search`, `ha_get_overview`, `ha_get_state`, `ha_search_entities` |\n| **Service & Device Control** | `ha_bulk_control`, `ha_call_service`, `ha_get_operation_status`, `ha_list_services` |\n| **System** | `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` |\n| **Todo Lists** | `ha_get_todo`, `ha_remove_todo_item`, `ha_set_todo_item` |\n| **Utilities** | `ha_eval_template`, `ha_install_mcp_tools`, `ha_report_issue` |\n| **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |\n\n\u003C!-- TOOLS_TABLE_END -->\n\u003C\u002Fdetails>\n\n---\n\n## 🔌 Custom Component (ha_mcp_tools)\n\nSome tools require a companion custom component installed in Home Assistant. Standard HA APIs do not expose file system access or YAML config editing. This component provides both.\n\n**Tools that require the component:**\n\n| Tool | Description |\n|------|-------------|\n| `ha_config_set_yaml` | Safely add, replace, or remove top-level YAML keys in `configuration.yaml` and package files (automatic backup, validation, and config check) |\n| `ha_list_files` | List files in allowed directories (www\u002F, themes\u002F, custom_templates\u002F) |\n| `ha_read_file` | Read files from allowed paths (config YAML, logs, www\u002F, themes\u002F, custom_templates\u002F, custom_components\u002F) |\n| `ha_write_file` | Write files to allowed directories |\n| `ha_delete_file` | Delete files from allowed directories |\n\nAll other tools work without the component. These five return an error with installation instructions if the component is missing.\n\nThese tools also require feature flags: `HAMCP_ENABLE_FILESYSTEM_TOOLS=true` (file tools) and `ENABLE_YAML_CONFIG_EDITING=true` (YAML editing). To enable the `ha_install_mcp_tools` installer tool, set `HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true`.\n\n### Install using HACS (recommended)\n\n[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https:\u002F\u002Fmy.home-assistant.io\u002Fbadges\u002Fhacs_repository.svg)](https:\u002F\u002Fmy.home-assistant.io\u002Fredirect\u002Fhacs_repository\u002F?owner=homeassistant-ai&repository=ha-mcp&category=integration)\n\nTo add manually: open **HACS** > **Integrations** > three-dot menu > **Custom repositories** > add `https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp` (category: Integration) > **Download**.\n\nAfter installing, restart Home Assistant. Then open **Settings** > **Devices & Services** > **Add Integration** and search for **HA MCP Tools**.\n\n### Install manually\n\nCopy `custom_components\u002Fha_mcp_tools\u002F` from this repository into your HA `config\u002Fcustom_components\u002F` directory. Restart Home Assistant, then add the integration as described above.\n\n---\n\n## 🧠 Better Results with Agent Skills\n\nThis server gives your AI agent tools to control Home Assistant. For better configurations, pair it with [Home Assistant Agent Skills](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fskills) — domain knowledge that teaches the agent Home Assistant best practices.\n\nAn MCP server can create automations, helpers, and dashboards, but it has no opinion on *how* to structure them. Without domain knowledge, agents tend to over-rely on templates, pick the wrong helper type, or produce automations that are hard to maintain. The skills fill that gap: native constructs over Jinja2 workarounds, correct helper selection, safe refactoring workflows, and proper use of automation modes.\n\n### Bundled Skills (built-in)\n\nSkills from `homeassistant-ai\u002Fskills` are bundled and served as [MCP resources](https:\u002F\u002Fmodelcontextprotocol.io\u002Fdocs\u002Fconcepts\u002Fresources) via `skill:\u002F\u002F` URIs. Any MCP client that supports resources can discover them automatically — no manual installation needed.\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `ENABLE_SKILLS` | `true` | Serve skills as MCP resources. Resources are not auto-injected into context — clients must explicitly request them. |\n| `ENABLE_SKILLS_AS_TOOLS` | `true` | Expose skills and doc resources via `list_resources`\u002F`read_resource` tools. Resource-capable clients can set to `false` to reduce tool count. |\n\nSkills can still be installed manually for clients that prefer local skill files — see the [skills repo](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fskills) for instructions.\n\n---\n\n## 🧪 Dev Channel\n\nWant early access to new features and fixes? Dev releases (`.devN`) are published on every push to master.\n\n**[Dev Channel Documentation](docs\u002Fdev-channel.md)** — Instructions for pip\u002Fuvx, Docker, and Home Assistant add-on.\n\n---\n\n## 🤝 Contributing\n\nFor development setup, testing instructions, and contribution guidelines, see **[CONTRIBUTING.md](CONTRIBUTING.md)**.\n\nFor comprehensive testing documentation, see **[tests\u002FREADME.md](tests\u002FREADME.md)**.\n\n---\n\n## 🔒 Privacy\n\nHa-mcp runs **locally** on your machine. Your smart home data stays on your network.\n\n- **Configurable telemetry** — optional anonymous usage stats\n- **No personal data collection** — we never collect entity names, configs, or device data\n- **User-controlled bug reports** — only sent with your explicit approval\n\nFor full details, see our [Privacy Policy](PRIVACY.md).\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- **[Home Assistant](https:\u002F\u002Fhome-assistant.io\u002F)**: Amazing smart home platform (!)\n- **[FastMCP](https:\u002F\u002Fgithub.com\u002Fjlowin\u002Ffastmcp)**: Excellent MCP server framework\n- **[Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io\u002F)**: Standardized AI-application communication\n- **[Claude Code](https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-code)**: AI-powered coding assistant\n\n## 👥 Contributors\n\n### Maintainers\n\n- **[@julienld](https:\u002F\u002Fgithub.com\u002Fjulienld)** — Project creator & core maintainer.\n- **[@sergeykad](https:\u002F\u002Fgithub.com\u002Fsergeykad)** — Core maintainer.\n- **[@kingpanther13](https:\u002F\u002Fgithub.com\u002Fkingpanther13)** — Core maintainer.\n\n### Contributors\n\n- **[@bigeric08](https:\u002F\u002Fgithub.com\u002Fbigeric08)** — Explicit `mcp` dependency for protocol version 2025-11-25 support.\n- **[@airlabno](https:\u002F\u002Fgithub.com\u002Fairlabno)** — Support for `data` field in schedule time blocks.\n- **[@ryphez](https:\u002F\u002Fgithub.com\u002Fryphez)** — Codex Desktop UI MCP quick setup guide.\n- **[@Danm72](https:\u002F\u002Fgithub.com\u002FDanm72)** — Entity registry tools (`ha_set_entity`, `ha_get_entity`) for managing entity properties.\n- **[@Raygooo](https:\u002F\u002Fgithub.com\u002FRaygooo)** — SOCKS proxy support.\n- **[@cj-elevate](https:\u002F\u002Fgithub.com\u002Fcj-elevate)** — Integration & entity management tools (enable\u002Fdisable\u002Fdelete); person\u002Fzone\u002Ftag config store routing.\n- **[@maxperron](https:\u002F\u002Fgithub.com\u002Fmaxperron)** — Beta testing.\n- **[@kingbear2](https:\u002F\u002Fgithub.com\u002Fkingbear2)** — Windows UV setup guide.\n- **[@konradwalsh](https:\u002F\u002Fgithub.com\u002Fkonradwalsh)** — Financial support via [GitHub Sponsors](https:\u002F\u002Fgithub.com\u002Fsponsors\u002Fjulienld). Thank you! ☕\n- **[@knowald](https:\u002F\u002Fgithub.com\u002Fknowald)** — Area resolution via device registry in `ha_get_system_overview` for entities assigned through their parent device.\n- **[@zorrobyte](https:\u002F\u002Fgithub.com\u002Fzorrobyte)** — Per-client WebSocket credentials in OAuth mode, fixing WebSocket tool failures.\n- **[@deanbenson](https:\u002F\u002Fgithub.com\u002Fdeanbenson)** — Fixed `ha_deep_search` timeout on large Home Assistant instances with many automations.\n- **[@saphid](https:\u002F\u002Fgithub.com\u002Fsaphid)** — Config entry options flow tools (initial design, #590).\n- **[@adraguidev](https:\u002F\u002Fgithub.com\u002Fadraguidev)** — Fix menu-based config entry flows for group helpers (#647).\n- **[@transportrefer](https:\u002F\u002Fgithub.com\u002Ftransportrefer)** — Integration options inspection (`ha_get_integration` schema support, #689).\n- **[@teh-hippo](https:\u002F\u002Fgithub.com\u002Fteh-hippo)** — Fix blueprint import missing save step.\n- **[@smenzer](https:\u002F\u002Fgithub.com\u002Fsmenzer)** — Documentation fix.\n- **[@The-Greg-O](https:\u002F\u002Fgithub.com\u002FThe-Greg-O)** — REST API for config entry deletion.\n- **[@restriction](https:\u002F\u002Fgithub.com\u002Frestriction)** — Responsible disclosure: python_transform sandbox missing call target validation.\n- **[@lcrostarosa](https:\u002F\u002Fgithub.com\u002Flcrostarosa)** — Diagnostic and health monitoring tools concept (#675), inspiring system\u002Ferror logs, repairs, and ZHA radio metrics integration.\n\n---\n\n## 💬 Community\n\n- **[GitHub Discussions](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fdiscussions)** — Ask questions, share ideas\n- **[Issue Tracker](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fissues)** — Report bugs, request features, or suggest tool behavior improvements\n\n---\n\n## ⭐ Star History\n\n[![Star History Chart](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhomeassistant-ai_ha-mcp_readme_00e96a639f07.png)](https:\u002F\u002Fstar-history.com\u002F#homeassistant-ai\u002Fha-mcp&Date)\n","> ⚠️ **OAuth 模式中的重大变更（v7.0.0）** — 请在服务器端设置 `HOMEASSISTANT_URL`。同意表单现在仅接受令牌。[迁移指南 →](docs\u002FOAUTH.md#migrating-from-v6x)\n\n\u003Cdiv align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhomeassistant-ai_ha-mcp_readme_2daf00c3e699.png\" alt=\"Home Assistant MCP 服务器标志\" width=\"300\"\u002F>\n\n  # 非官方且强大的 Home Assistant MCP 服务器\n\n  \u003C!-- mcp-name: io.github.homeassistant-ai\u002Fha-mcp -->\n\n  \u003Cp align=\"center\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftools-88-blue\" alt=\"95+ 工具\">\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Freleases\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fhomeassistant-ai\u002Fha-mcp\" alt=\"发布\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Factions\u002Fworkflows\u002Fe2e-tests.yml\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Fhomeassistant-ai\u002Fha-mcp\u002Fe2e-tests.yml?branch=master&label=E2E%20Tests\" alt=\"E2E 测试\">\u003C\u002Fa>\n    \u003Ca href=\"LICENSE.md\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fhomeassistant-ai\u002Fha-mcp.svg\" alt=\"许可证\">\u003C\u002Fa>\n    \u003Cbr>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fcommits\u002Fmaster\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fcommit-activity\u002Fm\u002Fhomeassistant-ai\u002Fha-mcp.svg\" alt=\"活跃度\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fjlowin\u002Ffastmcp\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBuilt%20with-FastMCP-purple\" alt=\"基于 FastMCP 构建\">\u003C\u002Fa>\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpython\u002Frequired-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fhomeassistant-ai%2Fha-mcp%2Fmaster%2Fpyproject.toml\" alt=\"Python 版本\">\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fsponsors\u002Fjulienld\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitHub_Sponsors-☕-blueviolet\" alt=\"GitHub 赞助\">\u003C\u002Fa>\n  \u003C\u002Fp>\n\n  \u003Cp align=\"center\">\n    \u003Cem>一个全面的模型上下文协议（MCP）服务器，使 AI 助手能够与 Home Assistant 交互。\u003Cbr>\n    使用自然语言控制智能家居设备、查询状态、执行服务并管理您的自动化。\u003C\u002Fem>\n  \u003C\u002Fp>\n\u003C\u002Fdiv>\n\n---\n\n![Claude Desktop 演示](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhomeassistant-ai_ha-mcp_readme_6e3832b0f629.webp)\n\n---\n\n## 🚀 开始使用\n\n### 完整指南，帮助您快速上手 Claude Desktop（约10分钟）\n\n*无需付费订阅。* 点击您的操作系统：\n\n\u003Cp>\n\u003Ca href=\"https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Fguide-macos\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSetup_Guide_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white\" alt=\"macOS 设置指南\" height=\"120\">\u003C\u002Fa>    \u003Ca href=\"https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Fguide-windows\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSetup_Guide_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white\" alt=\"Windows 设置指南\" height=\"120\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n### 快速安装（约5分钟）\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🍎 macOS\u003C\u002Fb>\u003C\u002Fsummary>\n\n1. 前往 [claude.ai](https:\u002F\u002Fclaude.ai) 并登录（或创建免费账户）\n2. 打开 **终端** 并运行：\n   ```sh\n   curl -LsSf https:\u002F\u002Fraw.githubusercontent.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fmaster\u002Fscripts\u002Finstall-macos.sh | sh\n   ```\n3. [下载 Claude Desktop](https:\u002F\u002Fclaude.ai\u002Fdownload)（或重启：Claude 菜单 → 退出）\n4. 向 Claude 提问：**“你能看到我的 Home Assistant 吗？”**\n\n现在您已连接到演示环境！[连接您自己的 Home Assistant →](https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Fguide-macos\u002F#step-6-connect-your-home-assistant)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🪟 Windows\u003C\u002Fb>\u003C\u002Fsummary>\n\n1. 前往 [claude.ai](https:\u002F\u002Fclaude.ai) 并登录（或创建免费账户）\n2. 打开 **Windows PowerShell**（从开始菜单）并运行：\n   ```powershell\n   irm https:\u002F\u002Fraw.githubusercontent.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fmaster\u002Fscripts\u002Finstall-windows.ps1 | iex\n   ```\n3. [下载 Claude Desktop](https:\u002F\u002Fclaude.ai\u002Fdownload)（或重启：文件 → 退出）\n4. 向 Claude 提问：**“你能看到我的 Home Assistant 吗？”**\n\n现在您已连接到演示环境！[连接您自己的 Home Assistant →](https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Fguide-windows\u002F#step-6-connect-your-home-assistant)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🏠 Home Assistant OS（附加组件）\u003C\u002Fb>\u003C\u002Fsummary>\n\n1. 将仓库添加到您的 Home Assistant 实例：\n\n   [![添加仓库](https:\u002F\u002Fmy.home-assistant.io\u002Fbadges\u002Fsupervisor_add_addon_repository.svg)](https:\u002F\u002Fmy.home-assistant.io\u002Fredirect\u002Fsupervisor_add_addon_repository\u002F?repository_url=https%3A%2F%2Fgithub.com%2Fhomeassistant-ai%2Fha-mcp)\n\n2. 从附加组件商店安装 **“Home Assistant MCP 服务器”**，等待安装完成\n3. 点击 **启动**，然后打开 **日志** 选项卡以找到您的唯一 MCP URL\n4. 使用该 URL 配置您的 AI 客户端\n\n无需设置令牌或凭据——该附加组件会自动连接到 Home Assistant。\n\n[完整附加组件文档 →](homeassistant-addon\u002FDOCS.md)\n\n\u003C\u002Fdetails>\n\n### 🧙 适用于15+客户的设置向导\n\n**Claude Code、Gemini CLI、ChatGPT、Open WebUI、VSCode、Cursor 等。**\n\n\u003Cp>\n\u003Ca href=\"https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Fsetup\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FOpen_Setup_Wizard-4A90D9?style=for-the-badge\" alt=\"打开设置向导\" height=\"40\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n遇到问题？请查看 **[常见问题解答与故障排除](https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Ffaq\u002F)**\n\n---\n\n## 💬 您能用它做什么？\n\n只需用自然语言与 Claude 对话即可。以下是一些实际案例：\n\n| 您说 | 发生什么 |\n|---------|--------------|\n| *\"创建一个日落时开启门廊灯的自动化\"* | 创建具有正确触发器和动作的自动化 |\n| *\"在我的仪表板上添加一个天气卡片\"* | 更新您的 Lovelace 仪表板，添加新卡片 |\n| *\"运动传感器自动化不起作用，请调试一下\"* | 分析执行轨迹，找出问题并提出修复建议 |\n| *\"让我的早晨例行自动化也打开咖啡机\"* | 读取现有自动化，添加新动作并更新 |\n| *\"创建一个脚本，设置电影模式：调暗灯光、拉上百叶窗、打开电视\"* | 创建包含一系列动作的可重用脚本 |\n\n花更少的时间配置，更多的时间享受您的智能家居生活。\n\n---\n\n## ✨ 功能\n\n| 类别 | 功能 |\n|----------|--------------|\n| **🔍 搜索** | 模糊实体搜索、深度配置搜索、系统概览 |\n| **🏠 控制** | 任意服务、批量设备控制、实时状态 |\n| **🔧 管理** | 自动化、脚本、辅助实体、仪表板、区域、分区、组、日历、蓝图 |\n| **📊 监控** | 历史记录、统计信息、摄像头快照、自动化轨迹、ZHA 设备 |\n| **💾 系统** | 备份\u002F恢复、更新、附加组件、设备注册表 |\n\n\u003Cdetails>\n\u003C!-- TOOLS_TABLE_START -->\n\n\u003Csummary>\u003Cb>完整工具列表（88 个工具）\u003C\u002Fb>\u003C\u002Fsummary>\n\n| 类别 | 工具 |\n|----------|-------|\n| **附加组件** | `ha_call_addon_api`, `ha_get_addon` |\n| **区域与楼层** | `ha_config_list_areas`, `ha_config_list_floors`, `ha_config_remove_area`, `ha_config_remove_floor`, `ha_config_set_area`, `ha_config_set_floor` |\n| **自动化** | `ha_config_get_automation`, `ha_config_remove_automation`, `ha_config_set_automation` |\n| **蓝图** | `ha_get_blueprint`, `ha_import_blueprint` |\n| **日历** | `ha_config_get_calendar_events`, `ha_config_remove_calendar_event`, `ha_config_set_calendar_event` |\n| **摄像头** | `ha_get_camera_image` |\n| **仪表板** | `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` |\n| **设备注册表** | `ha_get_device`, `ha_remove_device`, `ha_update_device` |\n| **实体注册表** | `ha_get_entity_exposure`, `ha_get_entity`, `ha_remove_entity`, `ha_set_entity` |\n| **文件** | `ha_delete_file`, `ha_list_files`, `ha_read_file`, `ha_write_file` |\n| **组** | `ha_config_list_groups`, `ha_config_remove_group`, `ha_config_set_group` |\n| **HACS** | `ha_hacs_add_repository`, `ha_hacs_download`, `ha_hacs_repository_info`, `ha_hacs_search` |\n| **辅助实体** | `ha_config_list_helpers`, `ha_config_remove_helper`, `ha_config_set_helper`, `ha_get_helper_schema`, `ha_set_config_entry_helper` |\n| **历史与统计** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logs`, `ha_get_statistics` |\n| **集成** | `ha_delete_config_entry`, `ha_get_integration`, `ha_set_integration_enabled` |\n| **标签与分类** | `ha_config_get_category`, `ha_config_get_label`, `ha_config_remove_category`, `ha_config_remove_label`, `ha_config_set_category`, `ha_config_set_label` |\n| **脚本** | `ha_config_get_script`, `ha_config_remove_script`, `ha_config_set_script` |\n| **搜索与发现** | `ha_deep_search`, `ha_get_overview`, `ha_get_state`, `ha_search_entities` |\n| **服务与设备控制** | `ha_bulk_control`, `ha_call_service`, `ha_get_operation_status`, `ha_list_services` |\n| **系统** | `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` |\n| **待办事项** | `ha_get_todo`, `ha_remove_todo_item`, `ha_set_todo_item` |\n| **实用工具** | `ha_eval_template`, `ha_install_mcp_tools`, `ha_report_issue` |\n| **分区** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |\n\n\u003C!-- TOOLS_TABLE_END -->\n\u003C\u002Fdetails>\n\n---\n\n## 🔌 自定义组件 (ha_mcp_tools)\n\n部分工具需要在 Home Assistant 中安装配套的自定义组件。标准 HA API 并不提供对文件系统的访问或 YAML 配置的编辑功能，而该组件则同时提供了这两项能力。\n\n**需要该组件的工具：**\n\n| 工具 | 描述 |\n|------|-------------|\n| `ha_config_set_yaml` | 安全地在 `configuration.yaml` 和包文件中添加、替换或移除顶级 YAML 键（自动备份、验证和配置检查） |\n| `ha_list_files` | 列出允许目录中的文件（www\u002F、themes\u002F、custom_templates\u002F） |\n| `ha_read_file` | 从允许路径读取文件（配置 YAML、日志、www\u002F、themes\u002F、custom_templates\u002F、custom_components\u002F） |\n| `ha_write_file` | 将文件写入允许目录 |\n| `ha_delete_file` | 删除允许目录中的文件 |\n\n其他所有工具无需该组件即可正常工作。这五个工具若缺少该组件，则会返回错误并附上安装说明。\n\n这些工具还需要启用以下功能标志：`HAMCP_ENABLE_FILESYSTEM_TOOLS=true`（文件工具）和 `ENABLE_YAML_CONFIG_EDITING=true`（YAML 编辑）。要启用安装工具 `ha_install_mcp_tools`，请设置 `HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true`。\n\n### 使用 HACS 安装（推荐）\n\n[![打开你的 Home Assistant 实例，并在 Home Assistant 社区商店中打开一个仓库。](https:\u002F\u002Fmy.home-assistant.io\u002Fbadges\u002Fhacs_repository.svg)](https:\u002F\u002Fmy.home-assistant.io\u002Fredirect\u002Fhacs_repository\u002F?owner=homeassistant-ai&repository=ha-mcp&category=integration)\n\n手动添加方法：打开 **HACS** > **集成** > 三点菜单 > **自定义仓库** > 添加 `https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp`（类别：集成）> **下载**。\n\n安装完成后，请重启 Home Assistant。然后打开 **设置** > **设备与服务** > **添加集成**，搜索 **HA MCP Tools**。\n\n### 手动安装\n\n将此仓库中的 `custom_components\u002Fha_mcp_tools\u002F` 文件夹复制到你的 HA 的 `config\u002Fcustom_components\u002F` 目录下。重启 Home Assistant 后，按照上述步骤添加集成。\n\n---\n\n## 🧠 使用智能体技能获得更佳效果\n\n该服务器为你的 AI 智能体提供了控制 Home Assistant 的工具。为了获得更好的配置效果，建议将其与 [Home Assistant 智能体技能](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fskills) 结合使用——这些领域知识能够教会智能体 Home Assistant 的最佳实践。\n\nMCP 服务器可以创建自动化、辅助实体和仪表板，但它并不知道如何合理地组织它们。如果没有领域知识，智能体会倾向于过度依赖模板，选择错误类型的辅助实体，或者生成难以维护的自动化流程。而这些技能则填补了这一空白：它们提倡使用原生构建而非 Jinja2 替代方案，帮助正确选择辅助实体类型，提供安全的重构流程，并指导如何恰当地使用自动化模式。\n\n### 内置技能集\n\n来自 `homeassistant-ai\u002Fskills` 的技能被打包并作为 [MCP 资源](https:\u002F\u002Fmodelcontextprotocol.io\u002Fdocs\u002Fconcepts\u002Fresources) 通过 `skill:\u002F\u002F` URI 提供。任何支持资源的 MCP 客户端都可以自动发现这些技能，无需手动安装。\n\n| 设置 | 默认值 | 描述 |\n|---------|---------|-------------|\n| `ENABLE_SKILLS` | `true` | 将技能作为 MCP 资源提供。资源不会自动注入上下文——客户端必须显式请求才能获取。 |\n| `ENABLE_SKILLS_AS_TOOLS` | `true` | 通过 `list_resources`\u002F`read_resource` 工具公开技能和文档资源。支持资源的客户端可以将其设置为 `false`，以减少工具数量。 |\n\n对于希望使用本地技能文件的客户端，仍可手动安装技能——具体操作请参阅 [skills 仓库](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fskills)。\n\n---\n\n## 🧪 开发通道\n\n想要提前体验新功能和修复吗？每当有代码推送到主分支时，都会发布开发版本（`.devN`）。\n\n**[开发通道文档](docs\u002Fdev-channel.md)** — 包括 pip\u002Fuvx、Docker 和 Home Assistant 插件的使用说明。\n\n---\n\n## 🤝 贡献\n\n有关开发环境搭建、测试说明及贡献指南，请参阅 **[CONTRIBUTING.md](CONTRIBUTING.md)**。\n\n如需全面的测试文档，请查看 **[tests\u002FREADME.md](tests\u002FREADME.md)**。\n\n---\n\n## 🔒 隐私\n\nHa-mcp 在您的设备上**本地运行**。您的智能家居数据将始终保留在您的网络中。\n\n- **可配置的遥测功能** — 可选的匿名使用统计\n- **不收集个人数据** — 我们绝不会收集实体名称、配置或设备数据\n- **用户可控的错误报告** — 仅在您明确同意的情况下才会发送\n\n更多详细信息，请参阅我们的 [隐私政策](PRIVACY.md)。\n\n---\n\n## 📄 许可证\n\n本项目采用 MIT 许可证授权，详情请参阅 [LICENSE](LICENSE) 文件。\n\n---\n\n## 🙏 致谢\n\n- **[Home Assistant](https:\u002F\u002Fhome-assistant.io\u002F)**：令人惊叹的智能家居平台 (!)\n- **[FastMCP](https:\u002F\u002Fgithub.com\u002Fjlowin\u002Ffastmcp)**：优秀的 MCP 服务器框架\n- **[Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io\u002F)**：标准化的 AI 应用程序通信协议\n- **[Claude Code](https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-code)**：由 AI 驱动的编码助手\n\n## 👥 贡献者\n\n### 维护者\n\n- **[@julienld](https:\u002F\u002Fgithub.com\u002Fjulienld)** — 项目创建者及核心维护者。\n- **[@sergeykad](https:\u002F\u002Fgithub.com\u002Fsergeykad)** — 核心维护者。\n- **[@kingpanther13](https:\u002F\u002Fgithub.com\u002Fkingpanther13)** — 核心维护者。\n\n### 贡献者\n\n- **[@bigeric08](https:\u002F\u002Fgithub.com\u002Fbigeric08)** — 明确添加 `mcp` 依赖，以支持 2025-11-25 版本协议。\n- **[@airlabno](https:\u002F\u002Fgithub.com\u002Fairlabno)** — 支持计划时间块中的 `data` 字段。\n- **[@ryphez](https:\u002F\u002Fgithub.com\u002Fryphez)** — 提供 Codex 桌面 UI 的 MCP 快速设置指南。\n- **[@Danm72](https:\u002F\u002Fgithub.com\u002FDanm72)** — 提供实体注册表工具（`ha_set_entity`、`ha_get_entity`），用于管理实体属性。\n- **[@Raygooo](https:\u002F\u002Fgithub.com\u002FRaygooo)** — 支持 SOCKS 代理。\n- **[@cj-elevate](https:\u002F\u002Fgithub.com\u002Fcj-elevate)** — 提供集成与实体管理工具（启用\u002F禁用\u002F删除）；以及人员\u002F区域\u002F标签配置存储路由功能。\n- **[@maxperron](https:\u002F\u002Fgithub.com\u002Fmaxperron)** — 参与 Beta 测试。\n- **[@kingbear2](https:\u002F\u002Fgithub.com\u002Fkingbear2)** — 提供 Windows UV 设置指南。\n- **[@konradwalsh](https:\u002F\u002Fgithub.com\u002Fkonradwalsh)** — 通过 [GitHub Sponsors](https:\u002F\u002Fgithub.com\u002Fsponsors\u002Fjulienld) 提供资金支持。感谢！☕\n- **[@knowald](https:\u002F\u002Fgithub.com\u002Fknowald)** — 在 `ha_get_system_overview` 中，通过设备注册表解析区域信息，适用于通过父设备分配的实体。\n- **[@zorrobyte](https:\u002F\u002Fgithub.com\u002Fzorrobyte)** — 在 OAuth 模式下为每个客户端提供 WebSocket 凭证，修复了 WebSocket 工具失败的问题。\n- **[@deanbenson](https:\u002F\u002Fgithub.com\u002Fdeanbenson)** — 修复了大型 Home Assistant 实例中，包含大量自动化时 `ha_deep_search` 超时的问题。\n- **[@saphid](https:\u002F\u002Fgithub.com\u002Fsaphid)** — 提供配置条目选项流程工具（初始设计，#590）。\n- **[@adraguidev](https:\u002F\u002Fgithub.com\u002Fadraguidev)** — 修复基于菜单的组助手配置流程问题（#647）。\n- **[@transportrefer](https:\u002F\u002Fgithub.com\u002Ftransportrefer)** — 提供集成选项检查功能（支持 `ha_get_integration` 模式，#689）。\n- **[@teh-hippo](https:\u002F\u002Fgithub.com\u002Fteh-hippo)** — 修复蓝图导入时缺少保存步骤的问题。\n- **[@smenzer](https:\u002F\u002Fgithub.com\u002Fsmenzer)** — 修正文档内容。\n- **[@The-Greg-O](https:\u002F\u002Fgithub.com\u002FThe-Greg-O)** — 提供用于删除配置条目的 REST API。\n- **[@restriction](https:\u002F\u002Fgithub.com\u002Frestriction)** — 负责任地披露：python_transform 沙箱缺少调用目标验证。\n- **[@lcrostarosa](https:\u002F\u002Fgithub.com\u002Flcrostarosa)** — 提出诊断和健康监测工具的概念（#675），启发了系统\u002F错误日志、维修以及 ZHA 无线电指标的集成。\n\n---\n\n## 💬 社区\n\n- **[GitHub 讨论区](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fdiscussions)** — 提问、分享想法\n- **[问题追踪器](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fissues)** — 报告 bug、请求功能或建议改进工具行为\n\n---\n\n## ⭐ 星标历史\n\n[![星标历史图表](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhomeassistant-ai_ha-mcp_readme_00e96a639f07.png)](https:\u002F\u002Fstar-history.com\u002F#homeassistant-ai\u002Fha-mcp&Date)","# ha-mcp 快速上手指南\n\nha-mcp 是一个非官方的 Home Assistant MCP（Model Context Protocol）服务器，它允许 AI 助手（如 Claude、ChatGPT 等）通过自然语言直接控制你的智能家居设备、查询状态、执行服务及管理自动化。\n\n## 环境准备\n\n在开始之前，请确保满足以下条件：\n\n*   **操作系统**：macOS、Windows 或运行 Home Assistant OS 的设备。\n*   **Home Assistant 实例**：拥有一个可访问的 Home Assistant 实例（本地或远程）。\n*   **AI 客户端**：已安装支持 MCP 的 AI 客户端（推荐 **Claude Desktop**，也支持 Cursor、VSCode、Open WebUI 等）。\n*   **网络要求**：AI 客户端所在的机器需要能够网络连通你的 Home Assistant 地址。\n*   **前置依赖**：\n    *   macOS\u002FLinux: 需安装 `curl` 和 `bash`。\n    *   Windows: 需安装 `PowerShell`。\n    *   Python 环境（通常由安装脚本自动处理）。\n\n> **注意**：若需使用文件读写或 YAML 配置编辑功能，需在 Home Assistant 中额外安装配套的自定义组件 `ha_mcp_tools`（详见后文）。\n\n---\n\n## 安装步骤\n\n根据你的操作系统选择对应的安装方式。\n\n### 方案 A：macOS \u002F Windows (连接 Claude Desktop)\n\n此方案最适合个人开发者快速体验，无需付费订阅即可使用免费账户连接。\n\n#### 1. macOS 用户\n打开 **终端 (Terminal)**，运行以下一键安装脚本：\n\n```sh\ncurl -LsSf https:\u002F\u002Fraw.githubusercontent.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fmaster\u002Fscripts\u002Finstall-macos.sh | sh\n```\n\n#### 2. Windows 用户\n打开 **Windows PowerShell**（以管理员身份运行更佳），运行以下命令：\n\n```powershell\nirm https:\u002F\u002Fraw.githubusercontent.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fmaster\u002Fscripts\u002Finstall-windows.ps1 | iex\n```\n\n#### 3. 完成配置\n1.  下载并安装 [Claude Desktop](https:\u002F\u002Fclaude.ai\u002Fdownload)（如果已安装，请完全退出后重新启动）。\n2.  启动 Claude Desktop，在对话框中输入：`\"Can you see my Home Assistant?\"`\n3.  此时你将连接到默认的演示环境。若要连接你自己的 Home Assistant，请参考官方文档中的 \"Connect your own Home Assistant\" 步骤配置 URL 和 Token。\n\n---\n\n### 方案 B：Home Assistant OS (作为插件安装)\n\n如果你使用的是 Home Assistant OS，这是最简便的方式，无需手动配置 Token。\n\n1.  点击以下按钮将仓库添加到你的 Home Assistant 实例：\n    [![添加仓库](https:\u002F\u002Fmy.home-assistant.io\u002Fbadges\u002Fsupervisor_add_addon_repository.svg)](https:\u002F\u002Fmy.home-assistant.io\u002Fredirect\u002Fsupervisor_add_addon_repository\u002F?repository_url=https%3A%2F%2Fgithub.com%2Fhomeassistant-ai%2Fha-mcp)\n2.  进入 **设置** > **插件** > **插件商店**，搜索并安装 **\"Home Assistant MCP Server\"**。\n3.  启动插件，点击 **日志 (Logs)** 标签页，复制生成的唯一 **MCP URL**。\n4.  在你的 AI 客户端配置中填入该 URL 即可。\n\n---\n\n### 方案 C：其他客户端通用配置向导\n\n如果你使用的是 Claude Code, Gemini CLI, ChatGPT, Open WebUI, VSCode, Cursor 等其他工具：\n\n请访问官方配置向导页面获取针对特定客户端的详细配置指令：\n[🔗 打开配置向导 (Open Setup Wizard)](https:\u002F\u002Fhomeassistant-ai.github.io\u002Fha-mcp\u002Fsetup\u002F)\n\n---\n\n## 基本使用\n\n安装完成后，ha-mcp 会自动向 AI 暴露 88+ 个工具。你只需用自然语言描述需求，AI 即可调用相应工具操作 Home Assistant。\n\n### 基础对话示例\n\n在连接的 AI 聊天窗口中尝试以下指令：\n\n| 你的指令 (自然语言) | AI 执行的操作 |\n| :--- | :--- |\n| `\"Create an automation that turns on the porch light at sunset\"` | 创建一个新的自动化：日落时开启门廊灯。 |\n| `\"Add a weather card to my dashboard\"` | 修改 Lovelace 仪表盘，添加天气卡片。 |\n| `\"The motion sensor automation isn't working, debug it\"` | 分析自动化执行轨迹，定位问题并提供修复建议。 |\n| `\"Make my morning routine automation also turn on the coffee maker\"` | 读取现有的“晨间例行”自动化，追加开启咖啡机的动作并保存。 |\n| `\"Create a script that sets movie mode: dim lights, close blinds, turn on TV\"` | 创建一个新脚本，按顺序执行调暗灯光、关闭窗帘、开启电视。 |\n\n### 进阶功能：文件系统与 YAML 编辑\n\n若需让 AI 直接修改 `configuration.yaml` 或管理文件，需启用高级权限：\n\n1.  **安装自定义组件**：\n    *   推荐使用 **HACS** 安装：在 HACS 中添加仓库 `https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp` (类别选 Integration)，然后安装 **HA MCP Tools**。\n    *   或手动将 `custom_components\u002Fha_mcp_tools\u002F` 复制到 HA 配置目录。\n2.  **启用功能标志**：\n    在启动 ha-mcp 服务器时（或在插件配置中），设置以下环境变量：\n    *   `HAMCP_ENABLE_FILESYSTEM_TOOLS=true` (启用文件读写)\n    *   `ENABLE_YAML_CONFIG_EDITING=true` (启用 YAML 配置编辑)\n\n启用后，你可以直接对 AI 说：“帮我修改 configuration.yaml，添加一个全新的集成配置”，AI 将安全地执行文件写入和配置校验。","独居的开发者李明正在深夜赶工，突然想起出门时忘记关闭客厅的取暖器，且担心家中宠物是否安全，急需远程确认并调整家居状态。\n\n### 没有 ha-mcp 时\n- **操作繁琐割裂**：必须停下代码编写，手动解锁手机，打开 Home Assistant APP，层层点击菜单才能找到对应开关。\n- **状态查询困难**：无法直接通过自然语言询问“客厅温度多少”或“宠物摄像头在线吗”，需肉眼在仪表盘上逐个查找传感器数据。\n- **自动化门槛高**：若想临时创建一条“温度过高自动关暖气”的规则，需要进入复杂的后台配置界面编写 YAML 或调试可视化编辑器。\n- **多设备协同差**：同时控制灯光、窗帘和暖通设备时，需在多个页面间反复切换，难以实现一键式的场景联动。\n- **打断心流严重**：频繁在开发环境与智能家居控制之间切换注意力，导致编程思路中断，工作效率大幅降低。\n\n### 使用 ha-mcp 后\n- **语音即控**：直接在 Claude Desktop 中输入“关闭客厅取暖器并打开走廊灯”，ha-mcp 立即解析意图并调用服务执行，全程无需离开代码编辑器。\n- **自然语言查询**：随口问“现在客厅温度和湿度是多少？”，ha-mcp 实时读取传感器状态并用通俗语言反馈，信息获取零延迟。\n- **动态自动化生成**：指令“如果客厅温度超过 26 度就自动关暖气”，ha-mcp 自动构建并部署相应的自动化脚本，无需手动配置底层逻辑。\n- **复杂场景一键触发**：一句“我准备睡觉了”，ha-mcp 即可协调关闭所有非必要电器、拉上窗帘并开启安防模式，实现多设备无缝联动。\n- **专注力零损耗**：所有家居交互融入对话流中，开发者无需切换上下文，保持了深度的工作心流状态。\n\nha-mcp 将原本割裂的智能家居控制转化为自然的对话交互，让 AI 助手真正成为连接人与物理世界的智能中枢。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhomeassistant-ai_ha-mcp_2daf00c3.png","homeassistant-ai","The Unofficial Home Assistant AI Toolkit","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fhomeassistant-ai_5d0ed0f4.png","Community-built MCP server for AI-powered smart home control and skills for Agents, Unofficial but awesome! 🏠🤖",null,"homeassistant-mcp@qc-h.net","https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai",[81,85,89,93,96,100,103,107],{"name":82,"color":83,"percentage":84},"Python","#3572A5",94.2,{"name":86,"color":87,"percentage":88},"Astro","#ff5a03",4.8,{"name":90,"color":91,"percentage":92},"Shell","#89e051",0.4,{"name":94,"color":95,"percentage":92},"TypeScript","#3178c6",{"name":97,"color":98,"percentage":99},"Dockerfile","#384d54",0.2,{"name":101,"color":102,"percentage":99},"PowerShell","#012456",{"name":104,"color":105,"percentage":106},"JavaScript","#f1e05a",0,{"name":108,"color":109,"percentage":106},"CSS","#663399",2143,75,"2026-04-07T23:26:03","MIT","macOS, Windows, Linux","未说明",{"notes":117,"python":118,"dependencies":119},"该工具是一个连接 AI 助手与 Home Assistant 的 MCP 服务器，主要作为客户端工具运行（如 Claude Desktop、VSCode 等）或作为 Home Assistant 的插件运行。支持通过脚本在 macOS 和 Windows 上快速安装，也提供 Home Assistant OS 插件形式。部分高级功能（如文件系统访问、YAML 配置编辑）需要额外在 Home Assistant 中安装自定义组件 'ha_mcp_tools' 并开启相应的功能标志。无需昂贵的 GPU 资源，主要依赖网络连接和本地计算资源运行轻量级服务。","未说明 (需参考 pyproject.toml)",[120],"fastmcp",[13,52],"2026-03-27T02:49:30.150509","2026-04-08T13:03:34.848161",[],[126,131,136,141,146,151,156,161,166,171,176,181,186,191,196,201,206,211,216,221],{"id":127,"version":128,"summary_zh":129,"released_at":130},153891,"v7.2.0.dev338","## 开发版本\n\n**版本:** 7.2.0.dev338  \n**提交:** 35c4587  \n**分支:** master  \n\n这是一个自动构建的开发版本，请自行承担使用风险。\n\n如需稳定版本，请从[最新发布](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Freleases\u002Flatest)下载。\n\n### 安装\n\n**Docker（开发通道）：**\n```bash\ndocker pull ghcr.io\u002Fhomeassistant-ai\u002Fha-mcp:dev\n```\n\n**PyPI（开发通道）：**\n```bash\npip install ha-mcp-dev\n```\n","2026-04-07T20:55:37",{"id":132,"version":133,"summary_zh":134,"released_at":135},153892,"v7.2.0.dev337","## 开发版本\n\n**版本:** 7.2.0.dev337  \n**提交:** e0fce36  \n**分支:** master  \n\n这是一个自动构建的开发版本，请自行承担使用风险。\n\n如需稳定版本，请从[最新发布](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Freleases\u002Flatest)下载。\n\n### 安装\n\n**Docker（开发通道）：**\n```bash\ndocker pull ghcr.io\u002Fhomeassistant-ai\u002Fha-mcp:dev\n```\n\n**PyPI（开发通道）：**\n```bash\npip install ha-mcp-dev\n```\n","2026-04-07T14:44:12",{"id":137,"version":138,"summary_zh":139,"released_at":140},153893,"v7.2.0.dev336","## 开发版本\n\n**版本:** 7.2.0.dev336  \n**提交:** d5516ba  \n**分支:** master  \n\n这是一个自动构建的开发版本，请自行承担使用风险。\n\n如需稳定版本，请从[最新发布](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Freleases\u002Flatest)下载。\n\n### 安装\n\n**Docker（开发通道）：**\n```bash\ndocker pull ghcr.io\u002Fhomeassistant-ai\u002Fha-mcp:dev\n```\n\n**PyPI（开发通道）：**\n```bash\npip install ha-mcp-dev\n```\n","2026-04-07T14:10:02",{"id":142,"version":143,"summary_zh":144,"released_at":145},153894,"v7.2.0.dev335","## 开发版本\n\n**版本:** 7.2.0.dev335  \n**提交:** 4f2683c  \n**分支:** master  \n\n这是一个自动构建的开发版本，请自行承担使用风险。\n\n如需稳定版本，请从[最新发布](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Freleases\u002Flatest)下载。\n\n### 安装\n\n**Docker（开发通道）：**\n```bash\ndocker pull ghcr.io\u002Fhomeassistant-ai\u002Fha-mcp:dev\n```\n\n**PyPI（开发通道）：**\n```bash\npip install ha-mcp-dev\n```\n","2026-04-07T13:56:35",{"id":147,"version":148,"summary_zh":149,"released_at":150},153895,"v7.2.0.dev334","## 开发版本\n\n**版本:** 7.2.0.dev334  \n**提交:** c11d994  \n**分支:** master  \n\n这是一个自动构建的开发版本，请自行承担使用风险。\n\n如需稳定版本，请从[最新发布](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Freleases\u002Flatest)下载。\n\n### 安装\n\n**Docker（开发通道）：**\n```bash\ndocker pull ghcr.io\u002Fhomeassistant-ai\u002Fha-mcp:dev\n```\n\n**PyPI（开发通道）：**\n```bash\npip install ha-mcp-dev\n```\n","2026-04-07T13:23:29",{"id":152,"version":153,"summary_zh":154,"released_at":155},153896,"v7.2.0","### 新增\n\n- 添加托管 YAML 配置编辑工具 (ha_config_set_yaml)\n  ([#827](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F827))\n- 带分类体系、自动生成文档和设计模式的工具探索器\n  ([#839](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F839))\n- 添加通用的附加组件 API 代理工具 (ha_call_addon_api)\n  ([#641](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F641))\n- 添加对自动化\u002F脚本\u002F场景类别的支持\n  ([#677](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F677))\n- 将文档工具转换为 MCP 资源和技能引用\n  ([#806](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F806))\n- 添加 Python 3.14 支持\n  ([#700](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F700))\n- 基于搜索的工具发现，配备分类调用代理\n  ([#727](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F727))\n- **uat**: 添加 --mcp-env 标志和 tokens_first_input 指标\n  ([#791](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F791))\n\n### 变更\n\n- 感谢 @teh-hippo、@smenzer、@The-Greg-O；更新 @cj-elevate\n  ([`66b3bb8`](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fcommit\u002F66b3bb803fe0fcb4ac7172cce0dcf9f8cfb8979d))\n- 记录 OAuth v7.0.0 的重大变更（需提供 HOMEASSISTANT_URL）\n  ([#829](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F829))\n- 将硬编码路径替换为 \u003Crepo-root> 占位符\n  ([#797](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F797))\n\n### 修复\n\n- 减少上下文耗尽并提升调试时的追踪细节\n  ([#822](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F822))\n- 添加 ast-grep 规则以捕获静默错误处理的漏洞\n  ([#838](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F838))\n- 在所有搜索工具、徽章搜索和仪表板深度搜索中添加 exact_match 参数\n  ([#814](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F814))\n- 在 ha_get_overview 中提示连接错误，而非返回空数据\n  ([#812](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F812))\n- 解决容器重启时 OAuth 令牌刷新失效及状态丢失的问题\n  ([#790](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F790))\n- **addon**: 拒绝损坏或包含 URL 的秘密路径\n  ([#792](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F792))\n\n### 重构\n\n- 整合 5 个冗余工具（在 #806 后合并）\n  ([#813](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F813))\n\n---\n\u003Cdetails>\n\u003Csummary>内部变更\u003C\u002Fsummary>\n\n\n### 修复\n\n- 防止复杂问题导致问题分类超时\n  ([#832](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F832))\n\n### 杂项\n\n- 感谢 @transportrefer 对集成选项 schema 的支持\n  ([#689](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F689))\n- 感谢 @adraguidev 修复基于菜单的配置条目流程\n  ([#647](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F647))\n- 感谢 @saphid 设计配置条目选项流程\n  ([#590](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F590))\n- **deps**: 将 \u002Fsite 中的 astro 从 5.16.11 升级至 5.18.1\n  ([#826](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpu","2026-04-01T10:54:58",{"id":157,"version":158,"summary_zh":159,"released_at":160},153897,"v7.1.0","### 新增\n\n- 在写入工具调用时添加响应式最佳实践警告\n  ([#695](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F695))\n- 为模板助手模式的模式检查，向 `ha_get_helper_schema` 添加 `menu_option`\n  ([#759](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F759))\n- 将区域的 CRUD 工具整合为设置\u002F移除模式\n  ([#643](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F643))\n- 配置项流程 — 修复资源泄漏、菜单流程、模式检查以及更新插入操作\n  ([`d804c1a`](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fcommit\u002Fd804c1a1ebb652fa4adf34d10a5b0f0ea7d44826))\n\n### 变更\n\n- 更新贡献者列表 [contributors-updated]\n  ([`69494ed`](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fcommit\u002F69494edfeda6c70e64874d27989ce30013f77d73))\n- 添加 v7.0.0 版本 OAuth HOMEASSISTANT_URL 要求的重大变更通知\n  ([`60a6bfc`](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fcommit\u002F60a6bfc1ef8372a99dba944856da394bee5196e0))\n\n### 修复\n\n- 由于服务格式错误，`Ha_mcp_tools` 的可用性检查始终失败\n  ([#763](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F763))\n- 使用 REST API 进行 `ha_delete_config_entry`\n  ([#756](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F756))\n- 确保技能在 Docker 构建中被打包，并为 claude.ai 添加指导工具\n  ([#732](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F732))\n- 澄清 `ha_search_entities` 和 `ha_deep_search` 的描述，以防止工具误用\n  ([#761](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F761))\n- 对于空的日志簿，返回空的成功响应而非 `RESOURCE_NOT_FOUND`\n  ([#710](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F710))\n- 防止 `ha_config_set_automation` 中出现虚假成功和重复创建\n  ([#708](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F708))\n- 使用软件包版本作为 MCP 服务器版本，而非硬编码的 0.1.0\n  ([#744](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F744))\n- 将已弃用的 `color_temp\u002Fkelvin` 替换为适用于 HA 2026.3 的 `color_temp_kelvin`\n  ([#711](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F711))\n- 向 `ha_import_blueprint` 添加蓝图保存步骤 (#685)\n  ([#751](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F751))\n\n---\n\u003Cdetails>\n\u003Csummary>内部变更\u003C\u002Fsummary>\n\n\n### 新增\n\n- 为 contrib-pr-review 技能添加摘要输出\n  ([`f063734`](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fcommit\u002Ff06373452701402606cfcbfa8a85fec3a0bc6731))\n\n### 修复\n\n- 拒绝 python_sandbox 中非 Name\u002FAttribute 类型的调用目标\n  ([#772](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F772))\n\n### 杂务\n\n- **依赖**: 将 ghcr.io\u002Fastral-sh\u002Fuv 的 Docker 标签更新至 v0.10.11\n  ([#778](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F778))\n- **依赖**: 将 fastmcp 从 3.1.0 更新至 3.1.1\n  ([#764](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F764))\n- **依赖**: 在 \u002Fsite 中将 devalue 从 5.6.3 升级至 5.6.4\n  ([#754](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F754))\n- **依赖**: 将 ghcr.io\u002Fastral-sh\u002Fuv 的 Docker 标签更新至 v0.10.9\n  ([#742](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F","2026-03-18T10:50:57",{"id":162,"version":163,"summary_zh":164,"released_at":165},153898,"v7.0.0","### 新增\n\n- 修复 OAuth 同意表单中的 SSRF 和 XSS 漏洞（破坏性更改）\n  ([#748](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F748))\n- **uat**: 添加 ha_checks 运行后验证及 OpenAI 代理改进\n  ([#713](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F713))\n- 添加 ha_check_update_notes 工具，用于更新前的影响评估\n  ([#595](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F595))\n- 在 ha_get_overview 中包含持久化通知\n  ([#642](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F642))\n- 添加 Nabu Casa 及其他通过 Webhook 代理的通用远程访问功能\n  ([#554](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F554))\n- 将捆绑的 HA 技能作为 MCP 资源提供\n  ([#679](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F679))\n\n### 变更\n\n- 始终以草稿形式创建 PR，仅在用户请求时才标记为已准备好\n  ([#723](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F723))\n- 恢复在回滚中丢失的详细维护者描述\n  ([`01d744a`](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fcommit\u002F01d744a07114861d0bc908b26ee7c8947cc1633b))\n- 始终以草稿形式创建 PR，仅在用户请求时才标记为已准备好\n  ([`63d57ae`](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fcommit\u002F63d57ae7e4b96335b17fc7aaa5e9dcba3c20c51d))\n- 澄清 MCP URL 出现在附加组件日志中，而非 HA 日志中\n  ([#714](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F714))\n- 将 Home Assistant OS 附加组件添加到快速安装部分\n  ([#715](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F715))\n\n### 修复\n\n- **types**: 添加 mypy 类型检查并修复 47 处类型错误\n  ([#716](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F716))\n- 在 get_system_overview 中通过设备注册表解析实体区域\n  ([#729](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F729))\n- 在 OAuth 模式下使用基于客户端的凭据进行 WebSocket 连接\n  ([#704](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F704))\n- 从实体注册表解析脚本存储键 (#463)\n  ([#593](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F593))\n- Webhook 代理 Dockerfile 中为 Supervisor 构建复制路径\n  ([#725](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F725))\n\n---\n\u003Cdetails>\n\u003Csummary>内部变更\u003C\u002Fsummary>\n\n\n### 新增\n\n- **ci**: 为问题分类机器人添加自动标签分类功能\n  ([#745](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F745))\n\n### 修复\n\n- **ci**: 将 GITHUB_TOKEN 注入 HACS 配置，以确保可靠的端到端测试\n  ([#718](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F718))\n- **ci**: 修复生成空发布说明的日志提取问题\n  ([#707](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F707))\n\n### 杂项\n\n- **ci**: 将 GitHub Actions 的 dependabot 更新合并为单个 PR\n  ([#739](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F739))\n- **deps**: 将 fastmcp 从 3.0.2 更新至 3.1.0\n  ([#717](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F717))\n- **deps**: 将 ghcr.io\u002Fastral-sh\u002Fuv 的 Docker 标签更新至 v0.10.7\n  ([#697](https:\u002F\u002Fgithub.com\u002Fhomeassistant-ai\u002Fha-mcp\u002Fpull\u002F697))\n- **deps**: 将 svgo 从 4.0.0 升级至 4.0","2026-03-11T02:40:18",{"id":167,"version":168,"summary_zh":169,"released_at":170},153899,"v6.7.2","发布 v6.7.2\n","2026-03-04T10:36:41",{"id":172,"version":173,"summary_zh":174,"released_at":175},153900,"v6.7.1","发布 v6.7.1\n","2026-02-20T12:45:21",{"id":177,"version":178,"summary_zh":179,"released_at":180},153901,"v6.7.0","Release v6.7.0\n","2026-02-17T13:09:49",{"id":182,"version":183,"summary_zh":184,"released_at":185},153902,"v6.6.1","Release v6.6.1\n","2026-02-10T23:34:19",{"id":187,"version":188,"summary_zh":189,"released_at":190},153903,"v6.6.0","Release v6.6.0\n","2026-02-10T11:05:33",{"id":192,"version":193,"summary_zh":194,"released_at":195},153904,"v6.5.0","Release v6.5.0\n","2026-02-03T10:55:32",{"id":197,"version":198,"summary_zh":199,"released_at":200},153905,"v6.4.0","Release v6.4.0\n","2026-01-27T10:40:53",{"id":202,"version":203,"summary_zh":204,"released_at":205},153906,"v6.3.1","Release v6.3.1\n","2026-01-20T10:40:38",{"id":207,"version":208,"summary_zh":209,"released_at":210},153907,"v6.3.0","Release v6.3.0\n","2026-01-17T11:42:24",{"id":212,"version":213,"summary_zh":214,"released_at":215},153908,"v6.2.0","Release v6.2.0\n","2026-01-12T03:10:54",{"id":217,"version":218,"summary_zh":219,"released_at":220},153909,"v6.0.0","Release v6.0.0\n","2026-01-07T01:27:23",{"id":222,"version":223,"summary_zh":224,"released_at":225},153910,"v5.1.0","Release v5.1.0\n","2026-01-07T01:30:23"]