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实例（或您可以使用模拟实现进行测试）

安装

# 克隆仓库
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

配置

使用环境变量或.env文件配置服务器：

# 服务器配置
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. 传输层 - 处理通信协议（stdio, HTTP）
2. 中间件层 - 通过管道处理请求
3. 工具层 - 实现特定功能
4. 资源层 - 管理有状态资源

工具

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

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

示例工具注册：

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集成

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

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

// 使用Claude API
const messages = [
  { role: "user", content: "Turn on the lights in the living room" }
];

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

Cursor集成

要将Home Assistant MCP服务器与Cursor一起使用，请在您的.cursor/config/config.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输出

Cursor集成故障排除

如果您在使用MCP服务器与Cursor时遇到“failed to create client”错误：

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的身份验证
• 🔄 用于与Claude和其他AI助手集成的标准I/O (stdio) 传输

为什么选择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

3. 配置您的设置：

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

4. 使用Docker构建并启动：

   bash 复制代码

   # 标准构建
   ./docker-build.sh
   
   # 启动：
   docker compose up -d

Docker构建选项 🐳

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

1. 标准构建

./docker-build.sh

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

2. 语音支持构建

./docker-build.sh --speech

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

3. GPU加速构建

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

• 所有语音功能
• CUDA GPU加速
• 优化以实现更快的处理
• 使用Float16计算类型以提高性能

构建特性

• 🔄 自动资源分配
• 💾 内存感知构建
• 📊 CPU配额管理
• 🧹 自动清理
• 📝 详细的构建日志
• 📊 构建摘要和状态

环境配置 🔧

我实现了分层配置系统：

文件结构 📁

1. .env.example - 我的模板，包含所有选项
2. .env - 您的配置（从.env.example复制）
3. 环境覆盖：
   • .env.dev - 开发设置
   • .env.prod - 生产设置
   • .env.test - 测试设置

加载优先级 ⚡

文件按以下顺序加载：

1. .env（基础配置）
2. 环境特定文件：
   • NODE_ENV=development → .env.dev
   • NODE_ENV=production → .env.prod
   • NODE_ENV=test → .env.test

后面的文件会覆盖前面的文件。

开发 💻

# 安装依赖
bun install

# 以开发模式运行
bun run dev

# 运行测试
bun test

# 带热重载运行
bun --hot run dev

# 构建生产版本
bun build ./src/index.ts --target=bun

# 运行生产构建
bun run start

性能比较 📊

文档 📚

核心文档

• 配置指南
• API文档
• 故障排除

高级特性

• 自然语言处理 - AI驱动的自动化分析和控制
• 自定义提示指南 - 创建和自定义AI行为
• 附加功能和工具 - 附加实用程序和高级功能

客户端集成 🔗

Cursor集成 🖱️

添加到.cursor/config/config.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"
      }
    }
  }
}

Claude Desktop 💬

添加到您的Claude配置：

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bun",
      "args": ["run", "start", "--port", "8080"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

命令行 💻

Windows用户可以使用提供的脚本：

1. 进入scripts目录
2. 运行start_mcp.cmd

附加功能

语音功能 🎤

MCP服务器可选地支持语音处理功能：

• 🗣️ 唤醒词检测（“hey jarvis”，“ok google”，“alexa”）
• 🎯 使用fast-whisper进行语音转文本
• 🌍 多语言支持
• 🚀 支持GPU加速

语音功能设置

前提条件

1. 🐳 安装并运行Docker
2. 🎮 支持CUDA的NVIDIA GPU（可选）
3. 💾 4GB+ RAM（建议8GB+）

配置

1. 在.env中启用语音功能：

   bash 复制代码

   ENABLE_SPEECH_FEATURES=true
   ENABLE_WAKE_WORD=true
   ENABLE_SPEECH_TO_TEXT=true
   WHISPER_MODEL_PATH=/models
   WHISPER_MODEL_TYPE=base

2. 选择您的STT引擎：

   bash 复制代码

   # 对于标准Whisper
   STT_ENGINE=whisper
   
   # 对于Fast Whisper（建议使用GPU）
   STT_ENGINE=fast-whisper
   CUDA_VISIBLE_DEVICES=0  # 设置GPU设备

可用模型 🤖

根据您的需求选择：

• tiny.en：最快，基本准确性
• base.en：良好的平衡（推荐）
• small.en：更高的准确性，速度较慢
• medium.en：高准确性，资源密集型
• large-v2：最佳准确性，非常资源密集型

启动语音功能

# 构建带语音支持
./docker-build.sh --speech

# 启动带语音功能：
docker compose -f docker-compose.yml -f docker-compose.speech.yml up -d

附加工具 🛠️

我在extra/目录中包含了一些强大的工具，以增强您的Home Assistant体验：

1. Home Assistant Analyzer CLI (ha-analyzer-cli.ts)

   • 使用AI模型进行深度自动化分析
   • 安全漏洞扫描
   • 性能优化建议
   • 系统健康指标

2. 语音转文本示例 (speech-to-text-example.ts)

   • 唤醒词检测
   • 语音转文本转录
   • 多语言支持
   • GPU加速支持

3. Claude Desktop设置 (claude-desktop-macos-setup.sh)

   • macOS上的自动Claude Desktop安装
   • 环境配置
   • MCP集成设置

有关详细用法说明和示例，请参阅附加文档。

许可 📄

MIT许可证。详见LICENSE。

作者 👨‍💻

由jango-blockchained创建

使用标准I/O传输运行 📝

MCP服务器支持JSON-RPC 2.0 stdio传输模式，以便直接与AI助手（如Claude）集成：

MCP Stdio特性

✅ JSON-RPC 2.0兼容性：完全支持MCP协议标准
✅ NPX支持：无需安装即可直接使用npx homeassistant-mcp运行
✅ 自动配置：创建必要的目录和默认配置
✅ 跨平台：适用于macOS、Linux和Windows
✅ Claude Desktop集成：准备好与Claude Desktop一起使用
✅ 参数验证：自动验证工具参数
✅ 错误处理：标准化错误代码和处理
✅ 详细日志：将日志写入文件而不污染stdio

选项1：使用NPX（最简单）

使用NPX直接运行MCP服务器而无需安装：

# 基本用法
npx homeassistant-mcp

# 或使用环境变量
HASS_URL=http://your-ha-instance:8123 HASS_TOKEN=your_token npx homeassistant-mcp

这将：

1. 临时安装包
2. 自动以stdio模式运行，并使用JSON-RPC 2.0传输
3. 创建日志目录
4. 如果不存在，则创建默认的.env文件

非常适合与Claude Desktop或其他MCP客户端集成。

与Claude Desktop集成

要将MCP与Claude Desktop一起使用：

1. 打开Claude Desktop设置
2. 转到“高级”选项卡
3. 在“MCP Server”下选择“Custom”
4. 输入命令：npx homeassistant-mcp
5. 点击“保存”

Claude现在将使用MCP服务器进行Home Assistant集成，允许您通过Claude直接控制智能家居。

选项2：本地安装

1. 更新您的.env文件以启用stdio传输：

   复制代码

   USE_STDIO_TRANSPORT=true

2. 使用stdio-start脚本运行服务器：

   bash 复制代码

   ./stdio-start.sh

   可用选项：

   复制代码

   ./stdio-start.sh --debug    # 启用调试模式
   ./stdio-start.sh --rebuild  # 强制重建
   ./stdio-start.sh --help     # 显示帮助

在stdio模式下运行时：

• 服务器通过stdin/stdout使用JSON-RPC 2.0格式进行通信
• 不启动HTTP服务器
• 禁用控制台日志以避免污染stdio流
• 所有日志都写入logs/目录中的日志文件

JSON-RPC 2.0消息格式

请求格式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tool-name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

响应格式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    // 工具特定的结果数据
  }
}

错误响应格式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32000,
    "message": "错误消息",
    "data": {} // 可选的错误详情
  }
}

通知格式（服务器到客户端）

{
  "jsonrpc": "2.0",
  "method": "notification-type",
  "params": {
    // 通知数据
  }
}

支持的错误代码

与Claude Desktop集成

要使用此MCP服务器与Claude Desktop：

1. 创建或编辑您的Claude Desktop配置：

   bash 复制代码

   # 在macOS上
   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # 在Linux上
   nano ~/.config/Claude/claude_desktop_config.json
   
   # 在Windows上
   notepad %APPDATA%\Claude\claude_desktop_config.json

2. 添加MCP服务器配置：

   json 复制代码

   {
     "mcpServers": {
       "homeassistant-mcp": {
         "command": "npx",
         "args": ["homeassistant-mcp"],
         "env": {
           "HASS_TOKEN": "your_home_assistant_token_here",
           "HASS_HOST": "http://your_home_assistant_host:8123"
         }
       }
     }
   }

3. 重启Claude Desktop。

4. 在Claude中，您现在可以使用Home Assistant MCP工具。

JSON-RPC 2.0消息格式

使用

使用NPX（最简单）

使用Home Assistant MCP服务器的最简单方法是通过NPX：

# 以stdio模式启动服务器
npx homeassistant-mcp

这将自动：

1. 以stdio模式启动服务器
2. 将JSON-RPC消息输出到stdout
3. 将日志消息输出到stderr
4. 如果不存在则创建日志目录

您可以将stderr重定向以隐藏日志并仅查看JSON-RPC输出：

npx homeassistant-mcp 2>/dev/null

手动安装

如果您希望全局或本地安装该包：

# 全局安装
npm install -g homeassistant-mcp

# 然后运行
homeassistant-mcp

或本地安装：

# 本地安装
npm install homeassistant-mcp

# 然后使用npx运行
npx homeassistant-mcp

高级用法