AI导哈

智能家居控制协议

Home Assistant MCP是一个连接AI助手与智能家居系统的协议，提供50多种工具，支持语音控制和多种传输方式。

  • by jango-blockchained
  • JavaScript
  • 本地部署
  • 58 星标
  • 更新于
在 GitHub 查看 jango-blockchained/advanced-homeassistant-mcp

使用说明

🏠 家庭助理MCP

和你的房子谈谈。 您的AI助手（Claude、GPT、Cursor、Copilot）通过模型上下文协议连接到家庭助手。50+工具，三个运输工具，一个 bunx 命令。

# ⚡ Fastest way to try it
bunx github:jango-blockchained/advanced-homeassistant-mcp

🚀 快速开始

你需要一个 家庭助手 实例和a 长期访问令牌 (在此处创建一个).

克劳德桌面版

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bunx",
      "args": ["github:jango-blockchained/advanced-homeassistant-mcp"],
      "env": {
        "HASS_HOST": "http://your-ha-instance:8123",
        "HASS_TOKEN": "your_long_lived_access_token"
      }
    }
  }
}

重启克劳德。 你完了。让它开灯。

光标/VS代码

Cursor — add to .cursor/mcp.json 
{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bunx",
      "args": ["github:jango-blockchained/advanced-homeassistant-mcp"],
      "env": {
        "HASS_HOST": "http://your-ha-instance:8123",
        "HASS_TOKEN": "your_long_lived_access_token"
      }
    }
  }
}
VS Code + MCP Extension

在 .env 文件并使用预先配置的 .vscode/mcp.json:

{
  "mcp.servers": {
    "homeassistant-mcp": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "dist/stdio-server.mjs"],
      "env": {
        "HASS_HOST": "${env:HASS_HOST}",
        "HASS_TOKEN": "${env:HASS_TOKEN}"
      }
    }
  }
}

Smithery（点击一下）

直接从安装 Smithery登记处 --不需要配置文件：

npx @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude

📦 所有安装选项

方法 命令
铁匠铺 （最简单） npx @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude
bunx （不安装） bunx github:jango-blockchained/advanced-homeassistant-mcp
新巴拿马型船舶 npx @jango-blockchained/homeassistant-mcp@latest
码头工人 docker run -d -p 7123:7123 --env-file .env ghcr.io/jango-blockchained/advanced-homeassistant-mcp:1.7.0
来源 git clone ... && bun install && bun run build:all && bun run start:stdio
npm全局 npm add -g @jango-blockchained/homeassistant-mcp && homeassistant-mcp

可用的Docker标签：

  • latest -最新稳定版本
  • 1.7.3, 1.7, 1 -标记版本
  • dev -主分支机构的最新开发版本

🎯 你能做什么

一旦连接，你就可以像和人说话一样和你的房子说话：

"Turn off all lights in the bedroom"
"Set the thermostat to 72°F"
"Lock all doors and start the vacuum"
"Show me energy consumption this week"
"What's the temperature in the living room?"
"Activate the movie scene"
"Notify everyone that dinner is ready"
"Check my Home Assistant health"
"Find orphaned devices with low battery"
"Analyze my light usage patterns"

每个命令都映射到以下命令之一 50+工具 --灯光、气候、媒体、锁、盖子、风扇、吸尘器、警报、场景、自动化、通知、历史、能源监测、维护等。

Full tool reference (all 50+ tools)
类别 工具
光 列表、获取、打开/关闭、亮度、色温、RGB、效果
气候 列表、获取、暖通空调模式、目标温度、风扇模式、加湿
媒体 列表、获取、播放/暂停、音量、来源、声音模式、随机播放
封面 列表、获取、打开/关闭、定位、倾斜、车库门
锁 使用代码支持进行列表、获取、锁定/解锁
粉丝 列表、获取、速度、振荡、方向、预设
真空吸尘器 列表、获取、启动/停止/停靠、点清理、风扇速度
警报 列表、获取、武装回家/离开/过夜、解除武装
开关 列表、获取、打开/关闭/切换
场景 列表，激活命名场景
自动化 列表、切换、触发、创建/编辑/删除
通知 通过HA渠道推送警报
历史 查询历史状态
附加组件 安装、配置、控制
包裹 HACS集成和自定义组件
维护 孤立设备、电池警告、能量分析
智能场景 无人值守模式、窗户/热量冲突、能源浪费
照明 动画、场景、展示、BPM/节拍检测
语音 唤醒词检测、语音转文本、语音命令
仪表盘 查询和管理Lovelace仪表板
模板 通过HA渲染Jinja2模板
待办事项 添加、更新、删除项目
痕迹 自动化/脚本执行跟踪
搜索 使用筛选器进行全文实体搜索
实体状态 获取任何实体的当前状态
错误日志 使用筛选查询HA错误日志

完整文档： 工具参考

🎙️ 语音功能（语音控制）

将您的设置转换为完全语音控制的智能家居助手。语音集成提供了以隐私为中心的本地语音处理。

  • 唤醒词检测：技术支持 wyoming-openwakeword （默认值：“Hey Jarvis”）。
  • 语音到文本：使用快速、本地转录 faster-whisper.
  • 音频集成：直接集成PulseAudio，实现无缝麦克风接入。

要启用语音功能，请使用专用的Docker Compose文件：

docker-compose -f docker-compose.speech.yml up -d

请参阅 语音功能指南 有关详细的配置和设置说明。

🧱 建筑

┌──────────────┐     ┌─────────────────────┐     ┌──────────────────┐
│  AI Assistant │◄───►│   Home Assistant    │◄───►│  Your Smart Home │
│ (Claude/GPT)  │     │    MCP Server       │     │  (Home Assistant)│
└──────────────┘     └─────────────────────┘     └──────────────────┘
                         │           │
                    ┌────┘           └────┐
                    ▼                     ▼
              ┌────────────┐      ┌──────────────┐
              │  HTTP/WS   │      │    STDIO     │
              │ (Express)  │      │ (fastmcp v3) │
              └────────────┘      └──────────────┘

三次传输，一个代码库。选择一个适合您设置的工具——所有工具都显示相同的50多个工具。

  • 工作室 --适用于Claude Desktop、Cursor、VS Code（本地编辑器集成）
  • HTTP+WS --用于远程AI主机，具有JWT身份验证、速率限制和WebSocket流
  • HTTP（fastmcp） --无需定制中间件的轻量级HTTP传输

⚙️ 配置

最小设置。需要两个变量：

HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=eyJ...                          # long-lived access token

可选：

PORT=7123                                  # HTTP server port (default: 4000)
LOG_LEVEL=info                             # debug | info | warn | error
JWT_SECRET=...                             # for HTTP/WS auth (min 32 chars)

有关20+个环境变量的完整列表，请参阅 配置文档.

🛠️ 发展

bun install              # install dependencies
bun run build:all        # build all three entry points
bun test                 # run test suite (80% coverage threshold)
bun run lint             # ESLint + Prettier
bun run typecheck        # TypeScript type checking

内置于 包子，TypeScript，以及 fastmcp.三个切入点：

  • dist/index.cjs --基于Express的自定义MCP服务器上的HTTP+WS
  • dist/stdio-server.mjs --通过fastmcp v3进行STDIO
  • dist/http-server.mjs --通过fastmcp v3实现HTTP

📖 文档

完整文档位于 jango-blockchained.github.io/advanced-homeassistant-mcp --涵盖了安装、配置、所有50多种工具、部署（HTTP、STDIO、Smithery）、架构深度学习和指南。

🤝 贡献

PR欢迎。保持简单——相同的代码风格，添加测试，如果涉及公共API，则更新文档。

  1. 叉起来
  2. 分支它
  3. 编码它
  4. 测试IT
  5. PR它

看 贡献.md 查看完整指南。

📄 许可证

麻省理工学院——去创造一些很酷的东西。

您的智能家居使用MCP。现在你的AI也会说话。 🏠⚡🤖🔋

包括电池。 🔋

相关 MCP