家庭助手-MCP
项目介绍
技术文档摘要
🏠 Home Assistant MCP
弥合AI助手与智能家居之间的差距 🚀
一个强大、安全且可扩展的模型上下文协议（MCP）服务器，使像Claude、GPT和Cursor这样的AI助手能够无缝地与Home Assistant交互。通过自然语言命令控制灯光、气候、自动化等。
✨ 功能概述
🤖 AI驱动的智能家居控制
- 自然语言处理：将“将客厅灯光调暗到50%”转化为实际设备命令
- 多助手支持：适用于Claude、GPT-4、Cursor和其他兼容MCP的助手
- 智能上下文：记住设备状态、关系和用户偏好
- Smithery集成：通过Smithery.ai一键安装和部署
🛡️ 企业级安全性
- 速率限制：通过可配置请求限制保护免受滥用
- 输入净化：防止XSS和注入攻击
- JWT认证：基于令牌的安全访问控制
- 安全头：全面保护Web漏洞
⚡ 高性能架构
- Bun运行时：比Node.js快4倍，并内置TypeScript支持
- 流式响应：长时间操作的实时更新
- 模块化设计：清晰的责任分离和可扩展插件系统
- 多种传输方式：HTTP REST API、WebSocket和标准I/O支持
🏠 全面的设备控制
- 照明控制：亮度、色温、RGB颜色和效果
- 气候管理：恒温器、HVAC模式、风扇控制和计划
- 自动化与场景：触发自动化、激活场景和管理例程
- 设备发现：智能设备列表，过滤和搜索
- 通知系统：通过Home Assistant的通知渠道发送警报
- 智能维护：查找孤儿设备、分析使用模式、能耗监控
- 智能场景：自动检测并管理无人在家、窗户/加热冲突、能源浪费
🚀 快速开始
几分钟内启动：
# 克隆并安装
git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-homeassistant-mcp
bun install
# 配置环境
cp .env.example .env
# 编辑.env文件以包含您的Home Assistant详细信息
# 启动服务器
bun run start:stdio
就这样！您的AI助手现在可以控制您的智能家居了。 🤖✨
📦 安装
前提条件
- 🚀 Bun (v1.0.26+) - 推荐
- 🏠 Home Assistant 实例
方案1：Smithery.ai（推荐快速设置）
Smithery 是一个MCP服务器注册表，使得安装非常简单：
# 安装到Claude桌面
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client claude
# 安装到Cursor
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client cursor
# 安装到VS Code
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client vscode
您将被提示配置：
- Home Assistant URL
- 长期访问令牌
- 可选设置（端口、调试模式）
详见SMITHERY_DEPLOYMENT.md中的详细部署指南。
方案2：NPX（快速启动）
npx @jango-blockchained/homeassistant-mcp@latest
方案3：Bunx与GitHub（无需登录NPM）
如果您无法登录NPM，可以使用Bunx直接从GitHub运行：
# 如果没有Bun，请先安装
curl -fsSL https://bun.sh/install | bash
# 然后从GitHub运行
bunx github:jango-blockchained/advanced-homeassistant-mcp
或者直接从Git安装：
bun add git+https://github.com/jango-blockchained/
advanced-homeassistant-mcp.git
homeassistant-mcp
方案4：Docker（容器化）
在Docker容器中运行MCP服务器：
# 拉取最新镜像
docker pull ghcr.io/jango-blockchained/advanced-homeassistant-mcp:latest
# 使用环境变量运行
docker run -d \
-e HOME_ASSISTANT_URL=http://your-ha-instance:8123 \
-e HOME_ASSISTANT_TOKEN=your_long_lived_access_token \
-p 4000:4000 \
--name homeassistant-mcp \
ghcr.io/jango-blockchained/advanced-homeassistant-mcp:latest
# 或者使用docker-compose（参见docker/目录中的示例）
可用的Docker标签：
latest- 最新稳定版本1.0.x- 特定版本dev- 主分支上的最新开发构建
方案5：本地安装
# 全局安装
bun add -g @jango-blockchained/homeassistant-mcp
# 或本地安装
bun add homeassistant-mcp
# 运行
homeassistant-mcp
方案6：从源代码（最灵活）
git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-homeassistant-mcp
bun install
bun run build
bun run start:stdio
🛠️ 使用
AI助手集成
Claude桌面
添加到您的claude_desktop_config.json：
{
"mcpServers": {
"homeassistant-mcp": {
"command": "bunx",
"args": ["github:jango-blockchained/advanced-homeassistant-mcp"]
}
}
}
或使用npx：
{
"mcpServers": {
"homeassistant-mcp": {
"command": "npx",
"args": ["@jango-blockchained/homeassistant-mcp@latest"]
}
}
}
VS Code + Claude扩展
.vscode/settings.json已预配置，可立即使用。
Cursor
添加到.cursor/config/config.json：
{
"mcpServers": {
"homeassistant-mcp": {
"command": "bunx",
"args": ["github:jango-blockchained/advanced-homeassistant-mcp"]
}
}
}
或使用npx：
{
"mcpServers": {
"homeassistant-mcp": {
"command": "npx",
"args": ["@jango-blockchained/homeassistant-mcp@latest"]
}
}
}
API使用
启动HTTP服务器：
bun run start -- --http
可用端点：
POST /api/tools/call- 执行工具GET /api/resources/list- 列出资源GET /api/health- 健康检查WebSocket /api/ws- 实时更新
配置
创建一个.env文件：
# Home Assistant
HASS_HOST=http://your-ha-instance:8123
HASS_TOKEN=your_long_lived_access_token
# 服务器
PORT=3000
NODE_ENV=production
# 安全性
JWT_SECRET=your-secret-key
RATE_LIMIT_WINDOW=15
RATE_LIMIT_MAX=50
🏗️ 架构
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ AI助手 │◄──►│ MCP服务器 │◄──►│ Home Assistant │
│ (Claude/GPT) │ │ │ │ │
└─────────────────┘ │ ┌─────────────┐ │ └─────────────────┘
│ │ 传输层 │ │
│ │ │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ 中间件层 │ │
│ │ │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ 工具层 │ │
│ │ │ │
└─────────────────┘
核心组件
- 传输层：HTTP、WebSocket、Stdio
- 中间件层：安全、验证、日志记录
- 工具层：设备控制、自动化、通知
- 资源管理器：状态管理和缓存
内置工具（共34个）
🎨 Aurora声光同步（10个工具）✨ 新功能！
- 🎵 音频分析：提取BPM、节拍、情绪、频率数据
- 🔍 设备扫描：查找兼容Aurora的灯光
- 📊 设备配置：测量延迟及同步能力
- 🎬 时间线渲染：生成预渲染的灯光秀
- ▶️ 播放控制：播放/暂停/停止/跳转时间线
- 📋 时间线管理：列出、导出、导入时间线
- 📈 状态监控：系统状态和统计
- 🎯 智能同步：设备特定的时间补偿
- 🌈 能力感知：RGB、可调白光、仅亮度支持
- 🎶 节拍检测：灯光与音乐同步脉冲
🎨 Aurora 是一个完整的声光同步系统，将您的Home Assistant灯光转变为专业灯光秀，同步到音乐！
🏠 设备控制（13个工具）
- 🔦 灯光控制：亮度、色温、RGB、效果
- 🌡️ 气候控制：HVAC模式、温度、风扇控制
- 📺 媒体播放器：播放、音量、来源、声音模式
- 🪟 覆盖物：百叶窗、窗帘、车库门、位置控制
- 🔒 锁：带密码支持的锁定/解锁
- 💨 风扇：速度、摆动、方向、预设
- 🤖 吸尘器：清洁、对接、定点清洁、风速
- 🚨 报警控制：布防/撤防模式、安全管理
- 🎛️ 通用控制：通用设备控制接口
⚙️ 自动化与场景（3个工具）
- 🎬 场景：激活预定义场景
- ⚙️ 自动化：列出、切换、触发自动化
- 🔧 自动化配置：创建/更新/删除复杂自动化
🔧 系统管理（6个工具）
- 📋 设备发现：按领域/区域列出和筛选设备
- 📱 通知：多通道警报系统
- 📊 历史：查询历史状态数据
- 📦 附加组件管理：安装、配置、控制附加组件
- 📦 包管理：HACS集成和自定义组件
- 🔔 事件订阅：实时SSE事件流
🧠 智能特性（2个工具）
-
🔧 维护工具：类似Spook的维护功能
- 查找孤儿/不可用设备
- 分析房间的灯光使用模式
- 监控能耗
- 设备健康检查，电池警告
- 实体清理建议
-
🧠 智能场景：智能自动化检测
- 无人在家：自动关闭灯光，降低气候
- 窗户/加热冲突：自动禁用加热
- 节能：检测白天灯光，待机电源
- 生成自动化配置
📖 参见完整工具参考获取详细文档
MCP特性
-
📝 提示：预定义的常见家庭自动化任务模板
- 早晨/晚上例行公事
- 节能建议
- 安全设置
- 气候优化
- 媒体控制
- 故障排除助手
-
📊 资源：直接访问Home Assistant的状态和配置
- 按类型列出设备（灯光、气候、传感器等）
- 区域/房间配置
- 自动化和场景列表
- 当前家庭状态的仪表板摘要
-
🛠️ 24个全面工具：完整的设备控制和智能自动化
- 参见完整工具参考获取所有可用工具
- 设备控制、自动化、系统管理和智能特性
- 自然语言到Home Assistant API的转换
🎯 示例命令
一旦集成，您的AI助手就能理解如下命令：
设备控制：
"关闭卧室的所有灯光"
"将恒温器设置为72°F"
"在客厅扬声器上播放音乐"
"打开车库门"
"锁上所有门"
"启动机器人吸尘器"
"将卧室风扇设置为50%"
自动化与场景：
"激活电影场景"
"触发早晨例行公事自动化"
"显示我所有的自动化"
信息与监控：
"客厅当前的温度是多少？"
"显示所有不可用的设备"
"哪些灯目前是开着的？"
通知：
"通知所有人晚餐准备好了"
"向我的手机发送警报"
智能维护：
"检查我的Home Assistant健康状况"
"查找孤儿或不可用的设备"
"分析我的灯光使用模式"
"显示我的能耗"
"哪些设备电池电量低？"
Aurora声光同步： ✨ 新功能！
"分析这个音乐文件并同步我的灯光"
"扫描可以做Aurora效果的灯光"
"配置我的客厅灯光进行同步"
"为这首歌创建一个灯光秀"
"播放我刚刚创建的时间线"
"暂停灯光秀"
"显示Aurora状态"
智能场景：
"我要离开家，激活离家模式"
"是否有窗户开着并且加热开启？"
"检查是否有浪费能源的问题"
"关闭一切，我要去度假"
"我可以做什么来节省能源？"
您还可以使用提示获得引导帮助：
"帮我设置早晨例行公事"
"显示节能技巧"
"如何控制我的媒体播放器？"
🤝 贡献
我们欢迎贡献！以下是参与的方式：
- 🍴 分叉仓库
- 🌿 创建功能分支
- 💻 修改代码
- 🧪 如适用，添加测试
- 📝 更新文档
- 🔄 提交拉取请求
开发设置
bun install
bun run build
bun test
代码风格
- TypeScript，严格模式
- ESLint用于代码质量
- Prettier用于格式化
- Husky用于提交前钩子
发布
此项目使用自动化发布到GitHub、npm和Docker。详情见AUTOMATED_RELEASES.md。
快速发布：
- 转到Actions → 版本提升和发布
- 点击运行工作流程
- 选择版本提升类型（补丁/次要/主要）
- 系统会自动：
- 📦 创建GitHub发布
- 📤 发布到npm
- 🐳 构建并推送Docker镜像
📄 许可证
MIT许可证 - 详情见LICENSE。
🙏 致谢
使用以下工具构建：
- Bun - 快速的JavaScript运行时
- Home Assistant - 开源的家庭自动化平台
- 模型上下文协议 - AI集成标准
将您的智能家居转变为AI驱动的体验