Home Assistant Model Context Protocol (MCP)
2025.03.24
13
TypeScript智能家居控制AI助手集成自动化管理位置服务开发效率
Home Assistant Model Context Protocol (MCP) 是一个标准化的协议，用于AI助手与Home Assistant之间的交互，提供安全、类型化和可扩展的接口来控制智能家居设备。它作为AI模型（如Claude、GPT等）与Home Assistant之间的桥梁，支持执行命令、检索智能家居信息、流式响应长时间操作等功能。
View on GitHub
Overview
基本能力
产品定位
Home Assistant MCP 是一个智能家居控制协议，旨在为AI助手提供与Home Assistant交互的标准接口，实现设备控制、信息检索和自动化管理。
核心功能
- 模块化架构：清晰的传输、中间件和工具分离
- 类型化接口：完全TypeScript类型化，提升开发者体验
- 多传输支持：标准I/O（stdin/stdout）和HTTP/REST API（支持Server-Sent Events流式传输）
- 中间件系统：验证、日志记录、超时和错误处理
- 内置工具：灯光控制（亮度、颜色等）、气候控制（恒温器、HVAC）
- 可扩展插件系统：轻松添加新工具和功能
- 流式响应：支持长时间操作
- 参数验证：使用Zod模式
- Claude & Cursor集成：为AI助手提供现成的实用工具
适用场景
- AI助手控制智能家居设备
- 自动化规则管理
- 实时状态更新和通知
- 语音控制和语音转文本功能
工具列表
- LightsControlTool：控制灯光亮度、颜色等
- ClimateControlTool：控制恒温器和HVAC系统
常见问题解答
- Cursor集成失败：确保使用正确的命令和参数，并验证服务器是否正确输出JSON-RPC消息到stdout。
- 调试模式：设置
DEBUG_STDIO=true环境变量以启用调试模式。 - 语音功能问题：确保Docker已安装并运行，且配置了正确的语音模型路径和类型。
使用教程
使用依赖
- Node.js 16+
- Home Assistant实例（或使用模拟实现进行测试）
- Bun运行时（v1.0.26+，可选）
- Docker（可选，推荐用于部署）
安装教程
# 克隆仓库
git clone https://github.com/your-repo/homeassistant-mcp.git
# 安装依赖
cd homeassistant-mcp
npm install
# 构建项目
npm run build
运行服务器
# 使用标准I/O传输启动（用于AI助手集成）
npm start -- --stdio
# 使用HTTP传输启动（用于API访问）
npm start -- --http
# 同时使用两种传输启动
npm start -- --stdio --http
调试方式
# 启用调试模式
DEBUG_STDIO=true npm start -- --stdio
# 查看日志
cat logs/*.log