Ha MCP Bridge

家庭助理MCP服务器

用于家庭助理与Claude.ai集成的模型上下文协议（MCP）服务器，使用纯Node.js HTTP构建，以实现最大兼容性。

🎉 特性

• 纯Node.js HTTP架构 -无Express依赖关系，与N8N MCP结构匹配
• Claude.ai工具发现修复 -实施 prompts/list 破解正确的工具发现
• OAuth 2.1+PKCE身份验证 -安全身份验证流程
• 真正的家庭助理集成 -使用API令牌连接到实际的HA实例
• 10个家庭助理工具:

- get_entities -获取所有HA实体或按域筛选 - call_service -呼叫HA服务以控制设备 - get_automations -获取所有HA自动化 - get_lights -获取所有灯光实体 - get_switches -获取所有交换机实体 - get_climate -获取气候/暖通空调实体 - get_sensors -获取传感器实体 - control_lights -通过动作、亮度和颜色控制灯光 - get_temperature_simple -用于测试的模拟温度数据 - test_simple -用于连接验证的简单测试工具

• 许可证管理 -通过专用端点注册和管理API令牌。

🚀 快速开始

选项1:Docker（推荐）

# Using pre-built images from GitHub Container Registry
docker run -d \
  --name ha-mcp-server \
  -p 3000:3000 \
  -e SERVER_URL=https://your-domain.com \
  -e HA_URL=https://your-ha-instance.com \
  -e HA_TOKEN=your_ha_token \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=your_secure_password \
  shaikeme/ha-mcp-server:latest

选项2：Docker编写

# Clone repository
git clone https://github.com/shaike1/ha-mcp-bridge.git
cd ha-mcp-bridge

# Use pre-built image
docker-compose -f docker-compose.registry.yml up -d

# Or build locally
docker-compose up -d

选项3：家庭助理附加组件（HAOS）

1. 将此存储库添加到您的家庭助手附加商店
2. 安装“家庭助理MCP服务器”插件
3. 使用您的公共URL和管理员密码进行配置
4. 启动附加组件
5. 使用附加URL连接到Claude.ai

选项4：手动安装

git clone https://github.com/shaike1/ha-mcp-bridge.git
cd ha-mcp-bridge
npm install
npm start

连接到Claude.ai

1. 在Claude.ai中添加MCP集成
2. 使用您的SERVER_URL
3. 使用管理员凭据进行身份验证
4. 开始用Claude控制家庭助理！

🔧 配置

家庭助理设置

1. 在Home Assistant中创建长效访问令牌：

- 转到个人资料→ 安全→ 长寿命访问令牌 - 创建新令牌 - 复制令牌值

1. 确保您的HA实例可以从MCP服务器访问

MCP服务器设置

服务器需要以下环境变量：

PORT=3001
SERVER_URL=https://your-domain.com
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your_secure_password
HA_URL=https://your-ha-instance.com
HA_TOKEN=your_ha_token_here

API代币管理

您可以使用 /tokens/register 端点：

curl -X POST -H "Content-Type: application/json" \
-d '{"description":"my-new-key","scope":"mcp"}' \
http://localhost:3007/tokens/register

🏗️ 建筑

此MCP服务器使用 纯Node.js HTTP （无Express）以匹配工作MCP服务器的架构，并确保与Claude.ai的最大兼容性。

关键组件

• OAuth 2.1+PKCE流程 -安全身份验证
• Claude.ai兼容性黑客 -为Claude.ai的非标准MCP行为实现变通方法
• 服务器发送事件（SSE） -实时工具广播
• 首页助手API集成 -对HA的直接REST API调用

第.ai条兼容性

此服务器为Claude.ai的非标准MCP行为实现了几个解决方法：

1. prompts/list 黑客 -Claude.ai只打电话 prompts/list，从来没有 tools/list
2. SSE工具广播 -通过服务器发送事件自动发送工具
3. 运输申报 -用途 streamable-http 传输类型

🔒 安全

• OAuth 2.1与PKCE用于安全身份验证
• 基于会话的身份验证管理
• 代码中没有硬编码的凭据
• 安全的令牌存储和验证

🐛 故障排除

第.ai条中“未提供工具”

• 确保OAuth身份验证成功完成
• 检查HA_URL和HA_TOKEN是否正确
• 验证家庭助理是否可以从MCP服务器访问

连接问题

• 检查SERVER_URL是否与您的实际域名匹配
• 验证SSL证书是否有效
• 确保端口3001可访问

Home Assistant API错误

• 验证HA_TOKEN是否具有适当的权限
• 查看Home Assistant日志以了解API错误
• 确保HA_URL格式正确（包括协议和端口）

📝 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 彻底测试
5. 提交拉取请求

🔗 相关项目

• N8N MCP服务器 -类似的架构
• 模型上下文协议 -MCP官方文件

______________________________________________________________________

由以下材料制成❤️ 家庭助理和Claude.ai社区