🏠 家庭助理MCP
](https://smithery.ai/server/@jango-blockchained/advanced-homeassistant-mcp)  ](https://www.npmjs.com/package/@jango-blockchained/homeassistant-mcp) ](https://github.com/jango-blockchained/advanced-homeassistant-mcp/pkgs/container/advanced-homeassistant-mcp)  
弥合人工智能助手和智能家居之间的差距 🚀
一个功能强大、安全且可扩展的模型上下文协议（MCP）服务器，使Claude、GPT和Cursor等AI助手能够与家庭助手无缝交互。通过自然语言命令控制您的灯光、气候、自动化等。
______________________________________________________________________
✨ 功能概述
🤖 人工智能智能智能家居控制
- 自然语言处理：将“将客厅灯光调暗至50%”转换为实际的设备命令
- 多助理支持：与Claude、GPT-4、Cursor和其他MCP兼容助手配合使用
- 智能上下文：记住设备状态、关系和用户偏好
- Smithery集成：通过一键安装和部署 Smithery.ai
🛡️ 企业级安全
- 速率限制：通过可配置的请求限制防止滥用
- 输入消毒：防止XSS和注入攻击
- JWT身份验证：基于令牌的安全访问控制
- 安全标头：针对web漏洞的全面保护
⚡ 高性能架构
- Bun运行时：内置TypeScript支持，比Node.js快4倍
- 流媒体响应：长时间运行操作的实时更新
- 模块化设计：使用可扩展插件系统进行清晰的关注点分离
- 多个传输：HTTP REST API、WebSocket和标准I/O支持
🏠 设备综合控制
- 照明控制：亮度、色温、RGB颜色和效果
- 气候管理：恒温器、暖通空调模式、风扇控制和调度
- 自动化与场景：触发自动化、激活场景和管理例程
- 设备发现：具有过滤和搜索功能的智能设备列表
- 通知系统：通过家庭助理的通知渠道发送警报
- 智能维护：查找孤立设备，分析使用模式，能源监控
- 智能场景：自动检测和管理无人在家、窗户/供暖冲突、能源浪费
______________________________________________________________________
🚀 快速开始
几分钟内起床跑步：
# Clone and install
git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-homeassistant-mcp
bun install
# Configure environment
cp .env.example .env
# Edit .env with your Home Assistant details
# Start the server
bun run start:stdio就是这样！你的AI助手现在可以控制你的智能家居。 🤖✨
______________________________________________________________________
📦 安装
先决条件
选项1:Smithery.ai（建议用于快速设置）
史密瑟里 是MCP服务器的注册表，使安装变得非常容易：
# Install to Claude Desktop
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client claude
# Install to Cursor
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client cursor
# Install to VS Code
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client vscode系统将提示您配置：
- 家庭助理URL
- 长寿命访问令牌
- 可选设置（端口、调试模式）
看 微笑_深度.md 获取详细的部署指南。
选项2:NPX（快速启动）
npx @jango-blockchained/homeassistant-mcp@latest选项3:Bunx与GitHub（无需NPM登录）
如果你无法登录npm，请使用Bunx直接从GitHub运行：
# Install Bun first if you don't have it
curl -fsSL https://bun.sh/install | bash
# Then run from 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服务器：
# Pull the latest image
docker pull ghcr.io/jango-blockchained/advanced-homeassistant-mcp:latest
# Run with environment variables
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
# Or use docker-compose (see docker/ directory for examples)可用的Docker标签：
latest-最新稳定版本1.0.x-具体版本dev-主分支机构的最新开发版本
选项5：本地安装
# Install globally
bun add -g @jango-blockchained/homeassistant-mcp
# Or locally
bun add homeassistant-mcp
# Run
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_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代码+副本/Claude扩展
这 .vscode/mcp.json 已预先配置，可立即与MCP扩展一起使用。发展：
- 确保您已构建项目：
npm run build:stdio - 在中配置环境变量
.env - MCP服务器将使用中的配置自动连接
.vscode/mcp.json
或者，您可以在VS代码设置中手动配置：
{
"mcp.servers": {
"homeassistant-mcp": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/dist/stdio-server.mjs"],
"env": {
"HASS_HOST": "${env:HASS_HOST}",
"HASS_TOKEN": "${env:HASS_TOKEN}"
}
}
}
}光标
增添 .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
# Server
PORT=3000
NODE_ENV=production
# To expose externally
HOST=0.0.0.0
# Security
JWT_SECRET=your-secret-key
RATE_LIMIT_WINDOW=15
RATE_LIMIT_MAX=50______________________________________________________________________
🏗️ 建筑
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ AI Assistant │◄──►│ MCP Server │◄──►│ Home Assistant │
│ (Claude/GPT) │ │ │ │ │
└─────────────────┘ │ ┌─────────────┐ │ └─────────────────┘
│ │ Transport │ │
│ │ Layer │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ Middleware │ │
│ │ Layer │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ Tools │ │
│ │ Layer │ │
└─────────────────┘核心组件
- 传输层：http、websocket、stdio·全球之声
- 中间件层：安全、验证、日志记录
- 工具层：设备控制、自动化、通知
- 资源管理器：状态管理和缓存
内置工具（共34个）
🎨 极光声光转换（10个工具）✨ 新
- 🎵 音频分析：提取BPM、节拍、情绪、频率数据
- 🔍 设备扫描：查找与Aurora兼容的灯光
- 📊 设备分析：测量同步的延迟和能力
- 🎬 时间线渲染：生成预渲染灯光秀
- ▶️ 回放控制：播放/暂停/停止/查找时间线
- 📋 时间线管理：列表、导出、导入时间表
- 📈 状态监控：系统状态和统计
- 🎯 智能同步：设备特定的定时补偿
- 🌈 能力意识：RGB，可调白色，仅支持亮度
- 🎶 节拍检测：灯光与音乐同步
🎨 极光 是一个完整的声光同步系统，可以将您的家庭助理灯光转换为与音乐同步的专业灯光秀！
🏠 设备控制（13个工具）
- 🔦 灯光控制：亮度、色温、RGB、效果
- 🌡️ 气候控制：暖通空调模式、温度、风扇控制
- 📺 媒体播放器：播放、音量、声源、声音模式
- 🪟 封面：百叶窗、窗帘、车库门、位置控制
- 🔒 锁定：使用代码支持锁定/解锁
- 💨 粉丝：速度、振荡、方向、预设
- 🤖 真空吸尘器：清洁、对接、局部清洁、风扇速度
- 🚨 报警控制：武装/解除武装模式、安全管理
- 🎛️ 通用控制：通用设备控制接口
⚙️ 自动化和场景（3个工具）
- 🎬 场景：激活预定义场景
- ⚙️ 自动化：列表、切换、触发自动
- 🔧 自动化配置：创建/更新/删除复杂的自动化
🔧 系统管理（6个工具）
- 📋 设备发现：按域/区域列出和筛选设备
- 📱 通知：多通道报警系统
- 📊 历史：查询历史状态数据
- 📦 附加组件管理：安装、配置、控制附加组件
- 📦 包管理：HACS集成和定制组件
- 🔔 事件订阅：实时SSE事件流
🧠 智能功能（2个工具）
- 🔧 维护工具：类似骗局的维护功能
- 查找孤立/不可用的设备 - 按房间分析光使用模式 - 监控能耗 - 带有电池警告的设备健康检查 - 实体清理建议
- 🧠 智能场景：智能自动化检测
- 无人在家：自动关灯，减少气候 - 车窗/加热冲突：自动禁用加热 - 节能：检测日间灯，备用电源 - 生成自动化配置
📖 看 完整工具参考 获取详细文档
MCP功能
- 📝 提示：用于常见家庭自动化任务的预定义提示模板
- 晨练/晚练 - 节能建议 - 安全设置 - 气候优化 - 媒体控制 - 故障排除助手
- 📊 资源：直接访问家庭助理状态和配置
- 按类型（灯、气候、传感器等）列出的设备列表 - 区域/房间配置 - 自动化和场景列表 - 显示当前主页状态的仪表板摘要
- 🛠️ 24种综合工具：全设备控制和智能自动化
- 看 完整工具参考 适用于所有可用工具 - 设备控制、自动化、系统管理和智能功能 - 自然语言到家庭助理API翻译
______________________________________________________________________
🎯 示例命令
集成后，您的AI助手可以理解以下命令：
设备控制：
“关掉卧室里的所有灯”\ “将恒温器设置为72°F”\ “在客厅扬声器上播放音乐”\ “打开车库门”\ “锁上所有门”\ “启动机器人吸尘器”\ “将卧室风扇设置为50%”
自动化和场景：
“激活电影场景”\ “启动晨间例行自动化”\ “显示我的所有自动化”
信息与监控：
“客厅里现在的温度是多少？”\ “显示所有不可用的设备”\ “目前哪些灯亮着？”
通知：
“通知大家晚餐准备好了”\ “向我的手机发送警报”
智能维护：
“检查我的家庭助理健康状况”\ “查找孤立或不可用的设备”\ “分析我的灯光使用模式”\ “显示我的能耗”\ “哪些设备的电池电量低？”
极光声光转换： ✨ 新
“分析此音乐文件并同步我的灯光”\ “扫描可以产生极光效果的灯光”\ “配置我的客厅灯光以进行同步”\ “为这首歌制作灯光秀”\ “播放我刚刚创建的时间线”\ “暂停灯光秀”\ “显示Aurora状态”
智能场景：
“我要出门了，激活外出模式”\ “有开着暖气的窗户吗？”\ “检查是否存在能源浪费问题”\ “把所有东西都关掉，我要去度假了”\ “我能做些什么来节约能源？”
您还可以使用提示获得指导性帮助：
“帮我制定一个晨间例行程序”\ “向我展示节能技巧”\ “我如何控制我的媒体播放器？”
______________________________________________________________________
🤝 贡献
我们欢迎捐款！以下是如何参与其中：
- 🍴 分叉存储库
- 🌿 创建要素分支
- 💻 进行更改
- 🧪 如果适用，添加测试
- 📝 更新文档
- 🔄 提交拉取请求
开发设置
bun install
bun run build
bun test代码风格
- 具有严格模式的TypeScript
- ESLint用于代码质量
- 格式化预处理
- Husky用于预提交挂钩
发布
此项目使用 自动化发布 GitHub、npm和Docker。看 自动清除.md 了解详情。
快速发布：
- 首选 行动 → 版本碰撞和释放
- 点击 运行工作流
- 选择版本凹凸类型（补丁/次要/主要）
- 系统自动：
- 📦 创建GitHub版本 - 📤 发布到npm - 🐳 构建并推送Docker镜像
______________________________________________________________________
📄 许可证
MIT许可证-请参阅 许可证 了解详情。
______________________________________________________________________
🙏 致谢
内置于❤️ 使用：
______________________________________________________________________
将您的智能家居转变为人工智能驱动的体验
