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服务器采用分层架构构建：

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

工具

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

此配置：

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

游标集成故障排除

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

确保您在 Cursor 配置中使用了正确的命令和参数
- Bash 脚本方法确保只有有效的 JSON-RPC 消息到达 Cursor
- 在尝试连接之前，通过运行 bun run build 确保服务器已构建
确保服务器正确地将 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 消息。
确保您的系统上安装了 grep（大多数系统默认应该可用）
尝试使用以下命令重新构建服务器： bash bun run build
通过在环境变量中设置 DEBUG_STDIO=true 启用调试模式

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

重启 Cursor
清除 Cursor 的缓存（帮助 > 开发者 > 清除缓存并重新加载）
使用类似的方法与 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（可选，用于更快的语音处理）

快速开始 🚀

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

使我的设置脚本可执行

chmod +x scripts/setup-env.sh

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

./scripts/setup-env.sh

或者指定环境：

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

强制覆盖现有文件：

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

配置您的设置：

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

使用 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

所有语音功能
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

后加载的文件会覆盖先加载的文件。

开发 💻

bash

安装依赖

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 中添加： 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 配置中添加： json { "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
🎮 NVIDIA GPU 支持 CUDA（可选）
💾 4GB+ 内存（推荐 8GB+）

配置

在 .env 文件中启用语音功能： bash ENABLE_SPEECH_FEATURES=true ENABLE_WAKE_WORD=true ENABLE_SPEECH_TO_TEXT=true WHISPER_MODEL_PATH=/models WHISPER_MODEL_TYPE=base
选择你的 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: 最佳准确度，非常资源密集型

启动带有语音功能

bash

构建带语音支持的镜像

./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 标准输入输出传输模式，以便直接与 Claude 等 AI 助手集成：

MCP 标准 I/O 特性

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

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

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

bash

基本用法

npx homeassistant-mcp

或者使用环境变量

HASS_URL=http://your-ha-instance:8123 HASS_TOKEN=your_token npx homeassistant-mcp

这将：

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

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

与 Claude Desktop 集成

要将 MCP 与 Claude Desktop 一起使用：

打开 Claude Desktop 设置
转到“高级”选项卡
在“MCP 服务器”下选择“自定义”
输入命令：npx homeassistant-mcp
点击“保存”Claude 现在将使用 MCP 服务器进行 Home Assistant 集成，允许您直接通过 Claude 控制智能家居。

选项2：本地安装

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

USE_STDIO_TRANSPORT=true
使用 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 消息格式

请求格式

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

响应格式

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

错误响应格式

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

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

json { "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 配置： bash

在 macOS 上

nano ~/Library/Application Support/Claude/claude_desktop_config.json

在 Linux 上

nano ~/.config/Claude/claude_desktop_config.json

在 Windows 上

notepad %APPDATA%Claudeclaude_desktop_config.json
添加 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" } } } }
重启 Claude Desktop。
在 Claude 中，现在您可以使用 Home Assistant MCP 工具了。

JSON-RPC 2.0 消息格式

使用方法

使用 NPX（最简单）

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

bash

以 stdio 模式启动服务器

npx homeassistant-mcp

这将自动：

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

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

bash npx homeassistant-mcp 2>/dev/null

手动安装

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

bash

全局安装

npm install -g homeassistant-mcp

然后运行

homeassistant-mcp

或者本地安装：

bash

本地安装

npm install homeassistant-mcp

然后使用 npx 运行

npx homeassistant-mcp

高级用法

服务配置

[{'mcpServers': {'homeassistant-mcp': {'args': ['run', 'start', '--port', '8080'], 'command': 'bun', 'env': {'NODE_ENV': 'production'}}}}, {'mcpServers': {'homeassistant-mcp': {'args': ['homeassistant-mcp'], 'command': 'npx', 'env': {'HASS_HOST': 'http://your_home_assistant_host:8123', 'HASS_TOKEN': 'your_home_assistant_token_here'}}}}]

来源

来源：github
链接：https://github.com/jango-blockchained/homeassistant-mcp