使用说明
仓鼠MCP
对您的家庭助理进行全面的AI调试和维护访问。
它能做什么？
Hamster MCP连接人工智能助手，如Claude、ChatGPT、Cursor和 其他——添加到您的家庭助理实例。它是为调试和 维护——当某些东西不工作时，你需要的那种访问权限 或者你想了解你的系统内部发生了什么。
- 调试语音助手 --“显示最近5次语音管道运行 以及为什么语音转文本失败”
- 检查物质网络 --“What Matter节点在我的网络中 有什么是无法到达的吗？"
- 审查系统健康状况 --“列出我的所有维修和诊断 系统”
- 调试自动化 --“最后一次给我看痕迹 运动自动化运行”
- 检查日志 --“向我显示上个小时的主管日志”或 “家庭助理核心日志中是否有任何错误？”
- 审计实体风险 --“哪些实体暴露于Alexa 而不是谷歌助手？"
- 管理蓝牙 --“哪些蓝牙扫描仪处于活动状态，以及 他们的连接统计数据是什么？"
它还处理日常任务——开灯、列出自动化、， 检查实体状态——但这不是它的重点。
运作原理
仓鼠MCP作为自定义集成在您的家庭助理中运行。它 通过三个源组公开HA的功能：
- 服务 --所有HA服务动作（灯光、气候、自动化、， 脚本等），带有完整的字段描述和选择器元数据
- WebSocket命令 （约200个命令）--实体/设备/区域 注册表、历史记录、系统日志、配置条目、诊断、修复、， 物质、辅助管道、语音/对话、云/Nabu Casa、身份验证 管理、跟踪调试、HACS等
- 主管 （仅限HA操作系统）--核心/主管/主机日志、附加组件 管理、备份、主机和网络信息
您的AI助手通过6个元工具发现可用的内容：
| 工具 | 目的 |
|---|---|
search |
按关键字在所有组中查找命令 |
explain |
获取命令的详细描述 |
schema |
获取参数类型和选择器详细信息 |
call |
执行命令 |
list_resources |
列出可用的指导文件 |
read_resource |
阅读指导文件 |
当你添加一个新的集成时，任何WebSocket命令或服务都会 寄存器可立即供AI使用——无需MCP服务器更新 需要。权衡：对话中的第一次互动可能需要 AI探索可用资源的时刻。
如何比较
家庭助理有几个MCP服务器。仓鼠是这样的 适合：
哈mcp （2k+颗星）
是最受欢迎的，有92个精心策划的工具，涵盖日常控制，
自动化管理、仪表板、HACS等。它的 ha_call_service
该工具是完全通用的——它可以调用任何HA服务，包括来自
自定义集成。对于日常使用来说，它非常棒。然而，它的另一个
90个工具只封装了HA WebSocket命令的一个子集。全部
子系统没有覆盖范围：
- 事项（调试、节点诊断、线程/wifi凭据）
- 辅助管道（创建/管理/运行/调试语音管道）
- 语音/对话（代理列表、句子管理、调试评分）
- 云/Nabu Casa（订阅、远程连接/断开连接、Alexa/谷歌 实体管理）
- 身份验证管理（列出/创建/删除用户，更改密码）
- 跟踪调试（设置断点，逐步实现自动化）
- 诊断和维修
- 蓝牙扫描仪管理
- 购物清单、应用程序凭据、webhooks、网络配置
validate_config,fire_event,extract_from_target,get_triggers_for_target
家庭助理vibecode代理 （500多颗星）专注于基于IDE的开发——编辑HA 配置文件、管理HACS包、从创建仪表板 光标或VS代码。这是一个由两部分组成的架构（HA插件+本地MCP 客户端）使用基于git的版本控制和回滚。
哈斯·麦克普 （280+颗星） 有意精简——仅限REST，没有WebSocket或Supervisor访问权限 自动化创建的引导提示。
hass-mcp服务器 （23颗星）也是像Hamster一样的自定义组件，但采用硬编码 工具和OAuth 2.0支持在浏览器中与Claude一起使用。
mcp服务器家庭助理 （存档）正在上传到Home Assistant Core本身——官方 第一方MCP支持即将到来。
仓鼠的位置： 完全动态访问所有~200个WebSocket 命令、每个服务和主管，通过6个元工具。 在HA中作为具有本机身份验证的自定义组件运行。专为 调试和维护，而不是日常设备控制。
你需要的
安装
HACS（推荐）
- 打开HACS→ 集成→ 三点菜单→ 自定义仓库.
- 添加
https://github.com/altendky/hamster-mcp与类别 整合. - 搜索 仓鼠MCP 在HACS中安装它。
- 重新启动家庭助理。
- 首选 设置→ 设备和服务 → 添加集成 → 仓鼠MCP.
手册
- 复制
custom_components/hamster_mcp目录到您的主页 助手config/custom_components/目录。 - 重新启动家庭助理。
- 首选 设置→ 设备和服务 → 添加集成 → 仓鼠MCP.
连接您的AI工具
集成运行后，将您的AI工具指向您的家 助理实例：
- 网址：
https://<your-ha-host>:<port>/api/hamster_mcp（例如。，http://homeassistant.local:8123/api/hamster_mcp) - 运输： 可流式传输的HTTP
网络接入
MCP端点由家庭助理本身提供服务，因此可以访问 无论你的HA实例在哪里。
- 本地AI工具 （克劳德桌面、光标等）只要 它们与您的HA实例位于同一网络上。
- 云AI工具 （Claude.ai、ChatGPT等）需要您的HA实例 可通过互联网访问 纳布之家, 反向代理或类似代理。
认证
一些人工智能工具会提示您通过家庭助理登录 自动——只需在登录屏幕出现时进行操作。其他 需要一个静态令牌：创建一个 长效访问令牌 在您的HA配置文件（安全项下）中，并将其作为不记名令牌提供给 您的AI工具的配置。将此令牌视为密码——不要 共享它或将其提交给版本控制。
兼容客户端
众所周知，这些人工智能工具可以与Hamster MCP配合使用。按照设置进行操作 在每个工具中添加MCP服务器的说明链接：
| 客户端 | 本地/云 | 安装指南 |
|---|---|---|
| Claude.ai | 云 | 自定义连接器 |
| ChatGPT | 云 | 开发者模式 |
| 克劳德桌面 | 本地 | 本地服务器 / 远程服务器 |
| 克劳德代码 | 本地 | MCP设置 |
| 光标 | 本地 | MCP设置 |
任何支持Streamable HTTP传输的MCP客户端都应该工作。 请参阅 完整客户列表 上 MCP网站。
试试看
连接后，尝试询问您的AI助手：
- “显示最近5次语音管道运行及其结果。”
- “有什么系统维修需要我检查吗？”
- “告诉我哪些自动装置参考了前门传感器及其最新的痕迹。”
如果你得到一个有用的答案，一切正常。
状态
仓鼠MCP处于早期释放状态，功能正常，发育活跃。 欢迎通过以下方式提供反馈和错误报告 GitHub问题.
许可证
根据以下任一方式获得许可：
- Apache许可证，版本2.0(特许通行证)
- MIT许可证(许可证-麻省理工学院)
由您选择。
