Home Assistant Model Context Protocol (MCP)

一种标准化协议，用于AI助手与Home Assistant进行交互，提供安全、类型化且可扩展的接口来控制智能家居设备。

概览

Model Context Protocol (MCP) 服务器作为AI模型（如Claude, GPT等）与Home Assistant之间的桥梁，使AI助手能够：

• 在Home Assistant设备上执行命令
• 获取有关智能家居的信息
• 流式传输长运行操作的响应
• 验证参数和输入
• 提供一致的错误处理

特性

• 模块化架构 - 传输、中间件和工具之间有清晰的分离
• 类型化接口 - 完全使用TypeScript类型定义以提高开发体验
• 多种传输方式：
  • 标准I/O (stdin/stdout) 用于CLI集成
  • HTTP/REST API 支持Server-Sent Events流式传输
• 中间件系统 - 验证、日志记录、超时和错误处理
• 内置工具：
  • 灯光控制（亮度、颜色等）
  • 气候控制（恒温器、HVAC）
  • 更多即将推出...
• 可扩展插件系统 - 轻松添加新工具和功能
• 流式响应 - 支持长时间运行的操作
• 参数验证 - 使用Zod模式
• Claude & Cursor集成 - 为AI助手准备好的实用程序

入门指南

前提条件

• Node.js 16+
• Home Assistant实例（或您可以使用模拟实现进行测试）

安装

bash

克隆仓库

git clone https://github.com/your-repo/homeassistant-mcp.git

安装依赖

cd homeassistant-mcp npm install

构建项目

npm run build

运行服务器

bash

使用标准I/O传输启动（适用于AI助手集成）

npm start -- --stdio

使用HTTP传输启动（适用于API访问）

npm start -- --http

同时使用两种传输方式启动

npm start -- --stdio --http

配置

通过环境变量或.env文件配置服务器：

dotenv

服务器配置

PORT=3000 NODE_ENV=development

执行设置

EXECUTION_TIMEOUT=30000 STREAMING_ENABLED=true

传输设置

USE_STDIO_TRANSPORT=true USE_HTTP_TRANSPORT=true

调试和日志

DEBUG_MODE=false DEBUG_STDIO=false DEBUG_HTTP=false SILENT_STARTUP=false

CORS设置

CORS_ORIGIN=*

架构

MCP服务器采用分层架构构建：

1. 传输层 - 处理通信协议（标准I/O, HTTP）
2. 中间件层 - 通过管道处理请求
3. 工具层 - 实现特定功能
4. 资源层 - 管理有状态资源

工具

工具是向MCP服务器添加功能的主要方式。每个工具：

• 有一个唯一的名称
• 接受类型化的参数
• 返回类型化的结果
• 可以流式传输部分结果
• 验证输入和输出

示例工具注册：

typescript import { LightsControlTool } from "./tools/homeassistant/lights.tool.js"; import { ClimateControlTool } from "./tools/homeassistant/climate.tool.js";

// 注册工具 server.registerTool(new LightsControlTool()); server.registerTool(new ClimateControlTool());

API

当使用HTTP传输时，服务器提供JSON-RPC 2.0 API：

• POST /api/mcp/jsonrpc - 执行一个工具
• GET /api/mcp/stream - 连接到SSE流以获取实时更新
• GET /api/mcp/info - 获取服务器信息
• GET /health - 健康检查端点

与AI模型的集成

Claude集成

typescript import { createClaudeToolDefinitions } from "./mcp/index.js";

// 生成Claude兼容的工具定义 const claudeTools = createClaudeToolDefinitions([ new LightsControlTool(), new ClimateControlTool() ]);

// 与Claude API一起使用 const messages = [ { role: "user", content: "打开客厅的灯" } ];

const response = await claude.messages.create({ model: "claude-3-opus-20240229", messages, tools: claudeTools });### 游标集成

要将 Home Assistant MCP 服务器与 Cursor 一起使用，请在您的 .cursor/config/config.json 文件中添加以下内容：

json { "mcpServers": { "homeassistant-mcp": { "command": "bash", "args": ["-c", "cd ${workspaceRoot} && bun run dist/index.js --stdio 2>/dev/null | grep -E {"jsonrpc":"2.0" "], "env": { "NODE_ENV": "development", "USE_STDIO_TRANSPORT": "true", "DEBUG_STDIO": "true" } } } }

此配置：

1. 使用 stdio 传输运行 MCP 服务器
2. 将所有 stderr 输出重定向到 /dev/null
3. 使用 grep 过滤 stdout 中包含 {"jsonrpc":"2.0" 的行，确保输出干净的 JSON-RPC 消息

游标集成故障排除

如果您在使用 MCP 服务器与 Cursor 时遇到“无法创建客户端”错误：

1. 确保您在 Cursor 配置中使用了正确的命令和参数

   • Bash 脚本方法确保只有有效的 JSON-RPC 消息到达 Cursor
   • 在尝试连接之前，通过运行 bun run build 确保服务器已构建

2. 确保服务器正确地将 JSON-RPC 消息输出到 stdout： bash bun run dist/index.js --stdio 2>/dev/null | grep -E {"jsonrpc":"2.0" > json_only.txt

   然后检查 json_only.txt 以验证它只包含有效的 JSON-RPC 消息。

3. 确保您的系统上安装了 grep（大多数系统默认应该可用）

4. 尝试使用以下命令重新构建服务器： bash bun run build

5. 通过在环境变量中设置 DEBUG_STDIO=true 启用调试模式

如果问题仍然存在，您可以尝试：

1. 重启 Cursor
2. 清除 Cursor 的缓存（帮助 > 开发者 > 清除缓存并重新加载）
3. 使用类似的方法与 Node.js： json { "command": "bash", "args": ["-c", "cd ${workspaceRoot} && node dist/index.js --stdio 2>/dev/null | grep -E {"jsonrpc":"2.0" "] }

许可证

MIT

贡献

欢迎贡献！请随时提交 Pull Request。

Home Assistant 的 MCP 服务器 🏠🤖

概述 🌐

MCP（Model Context Protocol）服务器是我为 Home Assistant 设计的轻量级集成工具，提供灵活的设备管理和自动化接口。它设计得快速、安全且易于使用。使用 Bun 构建以实现最大性能。

核心功能 ✨

• 🔌 通过 REST API 进行基本设备控制
• 📡 WebSocket/Server-Sent Events (SSE) 用于状态更新
• 🤖 简单的自动化规则管理
• 🔐 基于 JWT 的身份验证
• 🔄 标准 I/O (stdio) 传输，用于与 Claude 和其他 AI 助手集成

为什么选择 Bun？🚀

我选择 Bun 作为运行时有几个关键优势：

• ⚡ 极快的性能

  • 比 Node.js 快达 4 倍
  • 内置 TypeScript 支持
  • 优化的文件系统操作

• 🎯 一站式解决方案

  • 包管理器（比 npm/yarn 更快）
  • 打包器（无需 webpack）
  • 测试运行器（内置测试）
  • TypeScript 转译器

• 🔋 内置功能

  • SQLite3 驱动程序
  • .env 文件加载
  • WebSocket 客户端/服务器
  • 文件监视器
  • 测试运行器

• 💾 资源高效

  • 较低的内存使用
  • 更快的冷启动
  • 更好的 CPU 利用率

• 🔄 Node.js 兼容性

  • 运行大多数 npm 包
  • 与 Express/Fastify 兼容
  • 原生 Node.js API

前提条件 📋

• 🚀 Bun 运行时（v1.0.26+）
• 🏡 Home Assistant 实例
• 🐳 Docker（可选，推荐用于部署）- 🖥️ Node.js 18+（可选，用于语音功能）
• 🎮 支持 CUDA 的 NVIDIA GPU（可选，用于更快的语音处理）

快速开始 🚀

1. 克隆我的仓库： bash git clone https://github.com/jango-blockchained/homeassistant-mcp.git cd homeassistant-mcp

2. 设置环境： bash

使我的设置脚本可执行

chmod +x scripts/setup-env.sh

运行设置（默认为开发环境）

./scripts/setup-env.sh

或者指定环境：

NODE_ENV=production ./scripts/setup-env.sh

强制覆盖现有文件：

./scripts/setup-env.sh --force

1. 配置您的设置：

• 编辑 .env 文件并填写您的 Home Assistant 详细信息
• 必填：添加您的 HASS_TOKEN（长期访问令牌）

1. 使用 Docker 构建和启动： bash

标准构建

./docker-build.sh

启动：

docker compose up -d

Docker 构建选项 🐳

我的 Docker 构建脚本 (docker-build.sh) 支持不同的配置：

1. 标准构建

bash ./docker-build.sh

• 基本的 MCP 服务器功能
• REST API 和 WebSocket 支持
• 不包含语音功能

2. 启用语音功能的构建

bash ./docker-build.sh --speech

• 包含唤醒词检测
• 语音转文字功能
• 拉取所需的镜像：
  • onerahmet/openai-whisper-asr-webservice
  • rhasspy/wyoming-openwakeword

3. GPU 加速构建

bash ./docker-build.sh --speech --gpu

• 所有语音功能 …