HomeAssistant MCP

家庭助理模型上下文协议 (MCP)

人工智能助手与家庭助理交互的标准化协议，为控制智能家居设备提供安全、类型化和可扩展的接口。

概述

模型上下文协议 (MCP) 服务器充当 AI 模型（如 Claude、GPT 等）和 Home Assistant 之间的桥梁，使 AI 助手能够：

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

特征

模块化架构——传输、中间件和工具之间的清晰分离
类型化接口- 完全 TypeScript 类型化，以获得更好的开发人员体验
多种传输方式：
- 用于 CLI 集成的标准 I/O （stdin/stdout）
- 支持服务器发送事件的**HTTP/REST API，**用于流式传输
中间件系统- 验证、日志记录、超时和错误处理
内置工具：
- 灯光控制（亮度、颜色等）
- 气候控制（恒温器、暖通空调）
- 更多内容即将推出...
可扩展插件系统——轻松添加新工具和功能
流响应——支持长时间运行的操作
参数验证- 使用 Zod 模式
Claude 和 Cursor Integration - 为 AI 助手提供的现成实用程序

入门

先决条件

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

安装

# Clone the repository
git clone https://github.com/your-repo/homeassistant-mcp.git

# Install dependencies 
cd homeassistant-mcp
npm install

# Build the project
npm run build

运行服务器

# Start with standard I/O transport (for AI assistant integration)
npm start -- --stdio

# Start with HTTP transport (for API access)
npm start -- --http

# Start with both transports
npm start -- --stdio --http

配置

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

# Server configuration
PORT=3000
NODE_ENV=development

# Execution settings
EXECUTION_TIMEOUT=30000
STREAMING_ENABLED=true

# Transport settings
USE_STDIO_TRANSPORT=true
USE_HTTP_TRANSPORT=true

# Debug and logging
DEBUG_MODE=false
DEBUG_STDIO=false
DEBUG_HTTP=false
SILENT_STARTUP=false

# CORS settings
CORS_ORIGIN=*

建筑学

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

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

工具

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

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

工具注册示例：

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

// Register tools
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 - 健康检查端点

与人工智能模型的集成

克劳德积分

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

// Generate Claude-compatible tool definitions
const claudeTools = createClaudeToolDefinitions([
  new LightsControlTool(),
  new ClimateControlTool()
]);

// Use with 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
});

光标集成

要将 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 配置中使用正确的命令和参数
- Bash 脚本方法确保只有有效的 JSON-RPC 消息到达 Cursor
- 在尝试连接之前，通过运行bun run build确保服务器已构建
确保服务器正确地将 JSON-RPC 消息输出到标准输出：
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来启用调试模式

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

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

执照

麻省理工学院

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

家庭助理的 MCP 服务器 🏠🤖

概述🌐

MCP（模型上下文协议）服务器是我为 Home Assistant 开发的轻量级集成工具，提供灵活的设备管理和自动化接口。它旨在快速、安全且易于使用。采用 Bun 构建，以实现最佳性能。

核心功能✨

🔌 通过 REST API 进行基本设备控制
📡 WebSocket/服务器发送事件（SSE）用于状态更新
🤖 简单的自动化规则管理
🔐 基于 JWT 的身份验证
🔄 标准 I/O（stdio）传输，用于与 Claude 和其他 AI 助手集成

为什么是 Bun？🚀

我选择 Bun 作为运行时有几个主要好处：

⚡超快的性能
- 比 Node.js 快 4 倍
- 内置 TypeScript 支持
- 优化文件系统操作
🎯一体化解决方案
- 包管理器（比 npm/yarn 更快）
- Bundler（不需要 webpack）
- 测试运行器（内置测试）
- TypeScript 转译器
🔋内置功能
- SQLite3 驱动程序
- .env 文件加载
- WebSocket 客户端/服务器
- 文件观察器
- 测试运行器
💾资源高效
- 降低内存使用率
- 更快的冷启动
- 更好的 CPU 利用率
🔄 Node.js 兼容性
- 运行大多数 npm 包
- 兼容 Express/Fastify
- 原生 Node.js API

先决条件📋

🚀 Bun 运行时（v1.0.26+）
🏡家庭助理实例
🐳 Docker（可选，建议部署）
🖥️ Node.js 18+（可选，用于语音功能）
🎮 支持 CUDA 的 NVIDIA GPU（可选，用于更快的语音处理）

快速入门🚀

克隆我的存储库：

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

设置环境：

# Make my setup script executable
chmod +x scripts/setup-env.sh

# Run setup (defaults to development)
./scripts/setup-env.sh

# Or specify an environment:
NODE_ENV=production ./scripts/setup-env.sh

# Force override existing files:
./scripts/setup-env.sh --force

配置您的设置：

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

使用 Docker 构建并启动：

# Standard build
./docker-build.sh

# Launch:
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

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

发展💻

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Run with hot reload
bun --hot run dev

# Build for production
bun build ./src/index.ts --target=bun

# Run production build
bun run start

性能比较📊

手术	包子	Node.js
安装依赖项	~2秒	~15秒
冷启动	300毫秒	1000毫秒
构建时间	150毫秒	4000毫秒
内存使用情况	约150MB	约400MB

文档📚

核心文档

高级功能

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

客户端集成

光标集成🖱️

添加到.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 配置：

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

命令行💻

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

进入scripts目录
运行start_mcp.cmd

附加功能

语音功能🎤

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

🗣️ 唤醒词检测（“嘿贾维斯”，“ok google”，“alexa”）
🎯 使用快速耳语进行语音转文本
🌍 多语言支持
🚀 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 引擎：

# For standard Whisper
STT_ENGINE=whisper

# For Fast Whisper (GPU recommended)
STT_ENGINE=fast-whisper
CUDA_VISIBLE_DEVICES=0  # Set GPU device

可用型号🤖

根据您的需求选择：

tiny.en ：最快，基本准确
base.en ：良好的平衡（推荐）
small.en ：准确度更高，但速度较慢
medium.en ：高精度，资源密集型
large-v2 ：准确率最高，但耗费资源

使用语音功能启动

# Build with speech support
./docker-build.sh --speech

# Launch with speech features:
docker compose -f docker-compose.yml -f docker-compose.speech.yml up -d

额外工具🛠️

我在extra/目录中包含了几个强大的工具来增强您的 Home Assistant 体验：

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

请参阅Extras 文档以了解详细的使用说明和示例。

许可证📄

MIT 许可证。详情请参阅许可证。

作者👨‍💻

由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 服务器，无需安装：

# Basic usage
npx homeassistant-mcp

# Or with environment variables
HASS_URL=http://your-ha-instance:8123 HASS_TOKEN=your_token npx homeassistant-mcp

这将：

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

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

与 Claude Desktop 集成

要将 MCP 与 Claude Desktop 结合使用：

打开 Claude 桌面设置
转到“高级”选项卡
在“MCP 服务器”下，选择“自定义”
输入命令： npx homeassistant-mcp
点击“保存”

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

选项 2：本地安装

更新您的.env文件以启用 stdio 传输：
USE_STDIO_TRANSPORT=true
使用 stdio-start 脚本运行服务器：
./stdio-start.sh
可用选项：
./stdio-start.sh --debug # Enable debug mode ./stdio-start.sh --rebuild # Force rebuild ./stdio-start.sh --help # Show 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": {
    // Tool-specific result data
  }
}

错误响应格式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32000,
    "message": "Error message",
    "data": {} // Optional error details
  }
}

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

{
  "jsonrpc": "2.0",
  "method": "notification-type",
  "params": {
    // Notification data
  }
}

支持的错误代码

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

与 Claude Desktop 集成

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

创建或编辑您的 Claude Desktop 配置：
# On macOS nano ~/Library/Application\ Support/Claude/claude_desktop_config.json # On Linux nano ~/.config/Claude/claude_desktop_config.json # On 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：

# Start the server in stdio mode
npx homeassistant-mcp

这将自动：

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

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

npx homeassistant-mcp 2>/dev/null

手动安装

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

# Install globally
npm install -g homeassistant-mcp

# Then run
homeassistant-mcp

或者本地安装：

# Install locally
npm install homeassistant-mcp

# Then run using npx
npx homeassistant-mcp

Integrations

家庭助理模型上下文协议 (MCP)

概述

特征

入门

先决条件

安装

运行服务器

配置

建筑学

工具

API

与人工智能模型的集成

克劳德积分

光标集成

光标集成故障排除

执照

贡献

家庭助理的 MCP 服务器 🏠🤖

概述🌐

核心功能✨

为什么是 Bun？🚀

先决条件📋

快速入门🚀

Docker 构建选项🐳

1. 标准构造

2. 语音构建

3. GPU加速构建

构建功能

环境配置

文件结构📁

加载优先级⚡

发展💻

性能比较📊

文档📚

核心文档

高级功能

客户端集成

光标集成🖱️

克劳德桌面💬

命令行💻

附加功能

语音功能🎤

语音功能设置

先决条件

配置

可用型号🤖

使用语音功能启动

额外工具🛠️

许可证📄

作者👨‍💻

使用标准 I/O 传输运行

MCP Stdio 功能

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

与 Claude Desktop 集成

选项 2：本地安装

JSON-RPC 2.0 消息格式

请求格式

响应格式

错误响应格式

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

支持的错误代码

与 Claude Desktop 集成

JSON-RPC 2.0 消息格式

用法

使用 NPX（最简单）

手动安装

高级用法

Appeared in Searches