MCP 服务器

HomeAssistant MCP

智能设备控制 🎮 💡 灯光：亮度、颜色、RGB 🌡️ 气候：温度、暖通空调（HVAC）、湿度 🚪 遮盖物：位置和倾斜度 🔌 开关：开/关 🚨 传感器：状态监控智能组织 🏠 具有上下文感知的分组。稳健的架构 🛠️ 错误处理、状态验证...

远程shell执行

AI集成系统

访问服务器

README

Home Assistant 模型上下文协议 (MCP)

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

概述

模型上下文协议 (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 服务器采用分层架构构建：

传输层 - 处理通信协议（stdio、HTTP）
中间件层 - 通过管道处理请求
工具层 - 实现特定功能
资源层 - 管理有状态的资源

工具

工具是向 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"
      }
    }
  }
}

此配置：

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

解决 Cursor 集成问题

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

确保您在 Cursor 配置中使用正确的命令和参数
- bash 脚本方法确保只有有效的 JSON-RPC 消息到达 Cursor
- 确保在尝试连接之前通过运行 bun run build 构建服务器
确保服务器正确地将 JSON-RPC 消息输出到 stdout：
```
bun run dist/index.js --stdio 2>/dev/null | grep -E '\{"jsonrpc":"2\.0"' > json_only.txt
```
然后检查 json_only.txt 以验证它是否仅包含有效的 JSON-RPC 消息。
确保您的系统上安装了 grep（它应该在大多数系统上默认可用）
尝试使用以下命令重建服务器：
```
bun run build
```
通过在环境变量中设置 DEBUG_STDIO=true 来启用调试模式

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

重新启动 Cursor
清除 Cursor 的缓存（Help > Developer > Clear Cache and Reload）

使用类似的方法与 Node.js：

{
  "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 (模型上下文协议) 服务器是我用于 Home Assistant 的轻量级集成工具，提供了一个灵活的设备管理和自动化接口。它旨在快速、安全且易于使用。使用 Bun 构建，以实现最佳性能。

核心特性 ✨

🔌 通过 REST API 进行基本设备控制
📡 WebSocket/服务器发送事件 (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（可选，用于更快的语音处理）

快速开始 🚀

克隆我的存储库：

git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp

设置环境：

# 使我的设置脚本可执行
chmod +x scripts/setup-env.sh

# 运行设置（默认为开发环境）
./scripts/setup-env.sh

# 或指定一个环境：
NODE_ENV=production ./scripts/setup-env.sh

# 强制覆盖现有文件：
./scripts/setup-env.sh --force

配置您的设置：

使用您的 Home Assistant 详细信息编辑 .env 文件
必需：添加您的 HASS_TOKEN（长期访问令牌）

使用 Docker 构建和启动：

# 标准构建
./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 配额管理
🧹 自动清理
📝 详细的构建日志
📊 构建摘要和状态

环境配置 🔧

我实现了一个分层配置系统：

文件结构 📁

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

加载优先级 ⚡

文件按以下顺序加载：

.env（基本配置）
环境特定文件：
- 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

性能比较 📊

操作	Bun	Node.js
安装依赖	~2s	~15s
冷启动	300ms	1000ms
构建时间	150ms	4000ms
内存使用	~150MB	~400MB

文档 📚

核心文档

高级特性

自然语言处理 - 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 用户可以使用提供的脚本：

转到 scripts 目录
运行 start_mcp.cmd

附加功能

语音功能 🎤

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

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

语音功能设置

前提条件

🐳 已安装并运行 Docker
🎮 具有 CUDA 的 NVIDIA GPU（可选）
💾 4GB+ RAM（建议 8GB+）

配置

在 .env 中启用语音：

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

选择您的 STT 引擎：

# 对于标准 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 体验：

Home Assistant 分析器 CLI (ha-analyzer-cli.ts)
- 使用 AI 模型进行深度自动化分析
- 安全漏洞扫描
- 性能优化建议
- 系统健康指标
语音转文本示例 (speech-to-text-example.ts)
- 唤醒词检测
- 语音转文本转录
- 多语言支持
- GPU 加速支持
Claude Desktop 设置 (claude-desktop-macos-setup.sh)
- 适用于 macOS 的自动 Claude Desktop 安装
- 环境配置
- MCP 集成设置

有关详细的使用说明和示例，请参阅附加组件文档。

许可证 📄

MIT 许可证。有关详细信息，请参阅 LICENSE。

作者 👨‍💻

由 jango-blockchained 创建

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

MCP 服务器支持 JSON-RPC 2.0 stdio 传输模式，用于与 Claude 等 AI 助手直接集成：

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

这将：

临时安装软件包
自动以 JSON-RPC 2.0 传输在 stdio 模式下运行
创建一个 logs 目录用于日志记录
如果不存在，则创建一个默认的 .env 文件

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

与 Claude Desktop 集成

要将 MCP 与 Claude Desktop 一起使用：

打开 Claude Desktop 设置
转到“Advanced”选项卡
在“MCP Server”下，选择“Custom”
输入命令：npx homeassistant-mcp
点击“Save”

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

选项 2：本地安装

更新您的 .env 文件以启用 stdio 传输：
```
USE_STDIO_TRANSPORT=true
```

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

./stdio-start.sh

可用选项：

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

在 stdio 模式下运行时：

服务器使用 JSON-RPC 2.0 格式通过 stdin/stdout 进行通信
不启动 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": {
    // 通知数据
  }
}

支持的错误代码

代码	描述	含义
-32700	解析错误	接收到无效的 JSON
-32600	无效的请求	JSON 不是有效的请求对象
-32601	找不到方法	方法不存在或不可用
-32602	无效的参数	无效的方法参数
-32603	内部错误	内部 JSON-RPC 错误
-32000	工具执行	执行工具时出错
-32001	验证错误	参数验证失败

与 Claude Desktop 集成

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

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

# 在 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

添加 MCP 服务器配置：

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

重新启动 Claude Desktop。
在 Claude 中，您现在可以使用 Home Assistant MCP 工具。

JSON-RPC 2.0 消息格式

用法

使用 NPX（最简单）

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

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

这将自动：

在 stdio 模式下启动服务器
将 JSON-RPC 消息输出到 stdout
将日志消息发送到 stderr
如果 logs 目录不存在，则创建该目录

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

npx homeassistant-mcp 2>/dev/null

手动安装

如果您更喜欢全局或本地安装软件包：

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

# 然后运行
homeassistant-mcp

或者本地安装：

# 本地安装
npm install homeassistant-mcp

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

HomeAssistant MCP

README

Home Assistant 模型上下文协议 (MCP)

概述

特性

快速入门

前提条件

安装

运行服务器

配置

架构

工具

API

与 AI 模型集成

Claude 集成

Cursor 集成

解决 Cursor 集成问题

许可证

贡献

Home Assistant 的 MCP 服务器 🏠🤖

概述 🌐

核心特性 ✨

为什么选择 Bun？ 🚀

前提条件 📋

快速开始 🚀

Docker 构建选项 🐳

1. 标准构建

2. 启用语音的构建

3. GPU 加速的构建

构建特性

环境配置 🔧

文件结构 📁

加载优先级 ⚡

开发 💻

性能比较 📊

文档 📚

核心文档

高级特性

客户端集成 🔗

Cursor 集成 🖱️

Claude Desktop 💬

命令行 💻

附加功能

语音功能 🎤

语音功能设置

前提条件

配置

可用模型 🤖

启动语音功能

额外工具 🛠️

许可证 📄

作者 👨‍💻

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

MCP Stdio 特性

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

与 Claude Desktop 集成

选项 2：本地安装

JSON-RPC 2.0 消息格式

请求格式

响应格式

错误响应格式

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

支持的错误代码

与 Claude Desktop 集成

JSON-RPC 2.0 消息格式

用法

使用 NPX（最简单）

手动安装

高级用法

推荐服务器