家庭助理MCP服务器

已归档 -该项目已被以下项目所取代： - 哈mcp -社区维护的HA MCP服务器（约97个工具，覆盖95%的用例） - 哈mcp额外 -Gap MCP服务器（21个工具：文件系统、数据库、系统、集成）两者结合使用，实现全面覆盖。此回购仅供参考。

______________________________________________________________________

MCP（模型上下文协议）服务器，用于将家庭助理与克劳德代码和克劳德桌面集成。

关于

版本2.3.0 为Claude.ai和移动访问引入了生产就绪的OAuth 2.1支持 133工具 -域/系统/高级层中的73个API级工具、45个传统API工具（包括ha_mcp_capabilities）和15个根级工具。

V2.0.0分层架构（73个新工具）

域层：实体管理（34个工具）

场景（4个工具）：列出、激活、创建、删除场景
脚本（6个工具）：列出、执行、重新加载、创建、更新、删除脚本
输入助手 （8个工具）：创建和管理布尔值、数字、文本、选择、日期时间助手
区域和地带 （9个工具）：创建、更新、删除区域和分区；分配设备
设备注册表 （7个工具）：列出、获取、更新、启用/禁用设备；管理实体注册表

系统层：生命周期管理（26个工具）

附加组件管理 （9个工具）：列出、启动、停止、重新启动、安装、卸载、更新、配置附加组件
整合管理 （7个工具）：列出、发现、设置、配置、重新加载、删除集成
计算机危险判定系统 （5个工具）：浏览、安装、更新、删除家庭助理社区商店存储库
备份与恢复 （5个工具）：列出、创建、还原、获取信息、删除备份

高级层：高级用户功能（13个工具）

批量操作 （3个工具）：批量服务调用，通过WebSocket打开/关闭多个实体
配置搜索 （4个工具）：搜索实体、服务、自动化、配置
自动化调试 （3个工具）：获取执行跟踪、列出跟踪、获取诊断
自动化助手 （3个工具）：验证配置、测试条件、生成模板

传统API工具（44个工具）

实体管理：查询状态、历史和控制设备
配置：读取、写入和验证家庭助理配置文件
自动化：创建、更新、删除和列出自动化（基于文件）
搜索与发现：按名称、域、地区、州查找实体
组织：管理区域、标签和设备
活动监控：跟踪最近的实体状态更改
自然语言：处理命令并渲染Jinja2模板
系统信息：获取诊断、日志和系统运行状况
列表和助手：管理购物清单、待办事项清单
媒体和相机：控制媒体播放器并获取相机快照
能源与统计：查询能源数据和长期统计数据
人员跟踪：获取人员位置和设备跟踪器
事件：触发自定义事件并列出事件侦听器
日历：列出日历并检索日历事件
日志：获取人类可读的事件历史记录
蓝图：列出并导入自动化蓝图
通知：向移动应用程序和服务发送通知

根级工具（15个工具）

文件系统访问 （6个工具）：读取、写入、列出、删除、移动具有安全约束的文件
数据库访问 （5个工具）：在Home Assistant记录器数据库上执行SQL查询
系统命令 （4个工具）：执行shell命令、读取日志、检查磁盘使用情况、重新启动HA

权限系统

⚠️ 安全通知： 当前根级工具 自动授予所有权限 对于单用户部署。这适用于个人家庭自动化系统，但在多用户或互联网暴露的部署之前应进行审查。

根级工具分为三个具有安全约束的权限类别：

文件系统：访问/config、/ssl、/backup、/share、/media、/addons（块/etc、/usr、/bin、/sbin、/sys、/proc）
数据库：SQL查询仅限于家庭助理记录器表（白名单）
命令：在主机系统上执行Shell命令

预期用途： 单用户家庭自动化系统，用户拥有硬件，是唯一的运营商。

安装选项

选项1：家庭助理附加组件（推荐）

看 ADDON_INSTALL.md 有关Home Assistant附加组件的完整安装说明。

选项2：手动部署

通过SSH直接部署到您的家庭助理操作系统安装上。

注：建议使用附加组件（选项1），因为它会在GitHub的更新上自动部署。

# Build on your Mac
npm run build

# Deploy to Home Assistant (use /config for persistence)
scp -r dist/* root@homeassistant.local:/config/mcp-server/dist/
scp package*.json root@homeassistant.local:/config/mcp-server/

# SSH in and install dependencies
ssh root@homeassistant.local "cd /config/mcp-server && npm install --production"

配置

stdio运输

对于Claude Desktop和Claude Code，服务器使用SSH上的stdio传输。

当作为附加组件安装时，它会自动部署到 /config/mcp-server:

ssh root@homeassistant.local \
  "cd /config/mcp-server && SUPERVISOR_TOKEN='your_token' node dist/index.js"

使用OAuth 2.1的HTTP传输

版本2.3.0 为Claude.ai和移动客户端引入了生产就绪的OAuth 2.1支持。

OAuth实现详细信息

此服务器实现 2025年6月18日OAuth 2.1规范 对于MCP服务器：

RFC 8414：OAuth 2.0授权服务器元数据(.well-known/oauth-authorization-server)
RFC 9728：OAuth 2.0受保护的资源元数据(.well-known/oauth-protected-resource/mcp)
RFC 7591：动态客户端注册(/mcp/oauth/register)
RFC 8707：OAuth 2.0的资源指标（受众验证）
协议版本: MCP-Protocol-Version: 2025-06-18 HEAD请求上的标头

安全架构：令牌封装

服务器使用 代币包装 要保护家庭助理凭据，请执行以下操作：

客户收到：不透明令牌（加密安全的随机字符串）
服务器存储：SQLite中的Home Assistant访问/刷新令牌(/config/mcp-sessions.db)
代币生命周期：刷新时发布新的不透明令牌，撤销旧令牌
会话持续：通过SQLite存储幸存服务器重启

这确保了Home Assistant令牌永远不会离开服务器，也无法从客户端提取。

已知限制：Claude.ai OAuth连接

⚠️ 现状（2025年11月）： Claude.ai远程MCP连接失败 step=start_error 当使用家庭助理的原生OAuth时。

什么有效：

✅ OAuth 2.1规范合规性（2025年6月/2025-06-18）
✅ 动态客户端注册（RFC 7591）
✅ OAuth发现端点（RFC 8414、RFC 9728）
✅ 带有SQLite持久性的令牌包装
✅ 受众绑定（RFC 8707）
✅ 所有OAuth端点都返回有效响应

失败之处：

❌ Claude.ai的OAuth代理在客户端注册后停止
❌ 从不重定向到授权端点
❌ 错误： step=start_error 在Claude.ai URL中

根本原因： 这是一个已知的问题(人类学/克劳德编码#3515)在动态客户端注册后，使用Claude.ai的OAuth代理验证。OAuth流程完成：发现→ 注册→ 停止授权请求从未到达MCP服务器。

尝试修复（2025年11月7日）：

✅ 固定受众绑定符合2025年6月规范
✅ 制造 resource 授权请求中的必填参数
✅ 添加了双重保护的资源端点（有和没有 /mcp 后缀）
✅ 已验证 token_endpoint_auth_methods_supported 包括 client_secret_post
✅ 在上添加了HEAD端点 / 和 /mcp 用于协议发现
❌ 问题仍然存在-似乎是Claude.ai代理验证，而不是服务器实现

推荐方法： 使用 stdio传输 通过SSH从Claude Desktop和Claude Code进行可靠访问。请参阅下面的stdio传输配置。

替代方法（未经测试）： 第三方OAuth提供商（GitHub OAuth，Auth0）已确认与Claude.ai远程MCP服务器合作。然而，这改变了安全模型：

所有用户将共享一个家庭助理帐户
用户身份来自GitHub/Auth0，而不是Home Assistant
需要实现自定义授权逻辑

对于单用户部署，stdio传输更简单、更安全。

Claude.ai的设置（实验性-目前不起作用）

注：以下配置已完成并符合规范，但目前由于上述Claude.ai的OAuth代理验证问题而失败。

配置环境变量:

   TRANSPORT=http
   PORT=3000
   OAUTH_CLIENT_URL=https://your-public-url.com
   SUPERVISOR_TOKEN=your_ha_supervisor_token

暴露服务器：使用反向代理（nginx、Cloudflare隧道）通过HTTPS公开服务器

添加到Claude.ai:

- 转到Claude.ai MCP设置 - 添加服务器URL: https://your-public-url.com - Claude.ai将通过以下方式发现OAuth端点 .well-known/oauth-authorization-server - 预期结果： step=start_error 客户注册后

OAuth端点

当TRANSPORT=http时，服务器公开：

发现: /.well-known/oauth-authorization-server
资源元数据: /.well-known/oauth-protected-resource/mcp
动态注册: /mcp/oauth/register
授权: /auth/authorize （重定向到家庭助理）
代币: /auth/token （发布不透明的访问/刷新令牌）
撤销: /auth/revoke
MCP SSE端点: /mcp （需要Bearer代币）

会话存储

会话被持久化 /config/mcp-sessions.db （SQLite）具有：

会话：与会话ID链接的家庭助理访问/刷新令牌
opaque_tokes：映射到会话的客户端令牌
auth_codes：与会话链接的授权码
oauth_客户端：动态注册的OAuth客户端

会话在服务器重启后仍然有效，包括自动清理过期的令牌。

认证

stdio传输：需要将家庭助理长期访问令牌设置为 SUPERVISOR_TOKEN 环境变量。

http传输：使用OAuth 2.1流从Home Assistant获取令牌，然后向客户端发出不透明的令牌。

可用工具

实体管理（4个工具）

ha_get_states -获取实体的当前状态
ha_get_history -使用时间范围过滤器查询历史数据
ha_call_service -呼叫任何家庭助理服务来控制设备
ha_get_entity_details -获取特定实体的完整详细信息和属性

配置管理（6个工具）

ha_read_config -从/config目录读取配置文件
ha_write_config -写入或更新配置文件（自动备份）
ha_list_files -列出/config中的文件和目录
ha_validate_config -验证配置而不应用更改
ha_reload_config -重新加载自动化、脚本或核心配置
ha_list_backups -列出配置文件的可用备份

自动化管理（4个工具）

ha_create_automation -在automations.yaml中创建新的自动化
ha_update_automation -按ID更新现有自动化
ha_delete_automation -按ID删除自动化
ha_list_automations -列出所有带有ID和别名的自动化

搜索和发现（2个工具）

ha_search_entities -按名称、设备类、域、状态、区域或标签搜索实体
ha_get_stats -获取按域、设备类、区域或标签分组的实体计数统计信息

活动监测（1个工具）

ha_get_recent_activity -使用基于时间的筛选获取最近更改状态的实体

组织（3个工具）

ha_list_areas -列出所有具有实体计数的区域/房间
ha_list_labels -列出所有带有实体计数的标签/标记
ha_list_devices -列出具有区域过滤和名称搜索功能的设备

自然语言处理（2个工具）

ha_process_conversation -处理自然语言文本以控制设备
ha_render_template -使用HA模板引擎渲染Jinja2模板

系统监控（3个工具）

ha_system_info -获取Home Assistant系统信息和运行状况
ha_get_logs -带可选过滤功能的“获取回家助手”日志
ha_restart -重新启动家庭助理（需要确认）

高级系统（3个工具）

ha_get_supervisor_info -获取主管、核心、操作系统或主机信息
ha_list_integrations -列出所有加载的集成和组件
ha_get_diagnostics -获取系统诊断、运行状况信息和解决方案建议

列表和助手（3个工具）

ha_manage_shopping_list -管理购物清单项目（列出、添加、删除、完成）
ha_manage_todo -管理待办事项列表项（列表、添加、删除、完成）
ha_list_input_helpers -列出所有输入辅助实体（布尔值、数字、文本、选择、日期时间）

媒体和相机（2个工具）

ha_get_camera_snapshot -获取相机快照URL或base64编码的图像数据
ha_control_media_player -控制媒体播放器（播放、暂停、停止、音量等）

能源与统计（2个工具）

ha_get_energy_data -获取能源仪表板数据（太阳能、电池、电网）
ha_get_statistics -获取长期历史统计数据（有效期>10天）

人员跟踪（1个工具）

ha_get_person_location -获取人员的位置信息，包括区域、GPS和设备跟踪器

活动（2个工具）

ha_fire_event -使用可选数据有效负载触发自定义事件
ha_list_event_listeners -获取所有活动听众及其计数

日历（2个工具）

ha_list_calendars -获取所有日历实体
ha_get_calendar_events -获取带分页的日期范围的日历事件

日志（1个工具）

ha_get_logbook -通过实体过滤和分页获取人类可读的日志条目

蓝图（2个工具）

ha_list_blueprints -按领域列出可用蓝图（自动化、脚本）
ha_import_blueprint -从URL导入蓝图（GitHub gist等）

通知（1个工具）

ha_send_notification -向移动应用程序或通知服务发送通知

文件系统访问（6个工具-需要权限）

ha_read_file -读取有大小限制的文件内容（文本或base64编码的二进制文件）
ha_write_file -写入或创建带有安全检查的文件（阻止系统路径）
ha_list_directory -列出包含元数据（大小、修改、权限）的文件和目录
ha_delete_file -删除文件或目录（可选递归删除）
ha_move_file -移动或重命名文件/目录
ha_file_info -获取详细的文件元数据（权限、所有者、时间戳）

安全：阻止写入/etc、/usr、/bin、/sbin、/sys、/proc。允许/config、/ssl、/backup、/share、/media和/addons。

数据库访问（5个工具-需要权限）

ha_execute_sql -执行原始SQL查询（SELECT、INSERT、UPDATE、DELETE）
ha_get_state_history -使用筛选器从数据库中查询状态历史记录
ha_get_statistics -查询传感器数据统计表
ha_purge_database -删除具有可配置保留期的旧记录（销毁）
ha_database_info -获取数据库大小、表计数和行计数

安全：对/config/home-assistant_v2.db的只读访问。记录所有操作。

系统命令（4个工具-需要权限）

ha_execute_command -执行带有超时和输出限制的shell命令
ha_read_logs -读取具有行限制和grep过滤的HA日志
ha_get_disk_usage -显示关键目录的磁盘空间使用情况
ha_restart_homeassistant -重新启动家庭助理（需要确认）

安全：授予权限后具有完全根访问权限。记录所有命令。

发展

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run locally (requires HA_BASE_URL and SUPERVISOR_TOKEN)
node dist/index.js

项目结构

src/
├── index.ts              # Main entry point, tool registration
├── ha-client.ts          # Home Assistant API client
├── permissions.ts        # Session-based permission manager
├── types.ts              # TypeScript interfaces
├── transports/           # Transport adapters (stdio, HTTP)
└── tools/                # Tool implementations
    ├── states.ts         # Entity state tools
    ├── config.ts         # Configuration tools
    ├── automation.ts     # Automation management
    ├── system.ts         # System operations (API + root)
    ├── search.ts         # Entity search
    ├── activity.ts       # Recent activity
    ├── organization.ts   # Areas, labels, devices
    ├── conversation.ts   # NLP and templates
    ├── monitoring.ts     # System monitoring
    ├── helpers.ts        # Lists and input helpers
    ├── media.ts          # Media and cameras
    ├── energy.ts         # Energy data
    ├── persons.ts        # Person tracking
    ├── events.ts         # Event firing and listeners
    ├── calendars.ts      # Calendar entities and events
    ├── logbook.ts        # Logbook history
    ├── blueprints.ts     # Blueprint management
    ├── notifications.ts  # Notification services
    ├── filesystem.ts     # Filesystem access (root)
    └── database.ts       # Database access (root)

安全说明

根级工具要求每个会话都有明确的权限批准
文件系统写入被阻止到关键系统路径
数据库操作仅限于HA记录器数据库
记录所有特权操作
OAuth 2.1支持安全HTTP传输

用法

有关Claude Desktop/Code配置说明，请参阅主存储库README，或参阅 ADDON_INSTALL.md 用于附加安装。

Homeassistant MCP Server

快速接入

详细介绍