家庭助理模型上下文协议 (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 实例（或者您可以使用模拟实现进行测试）

安装

运行服务器

配置

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

建筑学

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

1. 传输层-处理通信协议（stdio，HTTP）

2. 中间件层- 通过管道处理请求

3. 工具层——实现特定功能

4. 资源层- 管理有状态资源

工具

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

• 有一个独特的名字

• 接受类型参数

• 返回输入的结果

• 可以流式传输部分结果

• 验证输入和输出

工具注册示例：

API

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

• POST /api/mcp/jsonrpc - 执行工具

• GET /api/mcp/stream - 连接到 SSE 流以获取实时更新

• GET /api/mcp/info - 获取服务器信息

• GET /health - 健康检查端点

与人工智能模型的集成

克劳德积分

光标集成

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

此配置：

1. 使用 stdio 传输运行 MCP 服务器

2. 将所有 stderr 输出重定向到 /dev/null

3. 使用 grep 过滤 stdout 中包含{"jsonrpc":"2.0"的行，确保输出干净的 JSON-RPC 输出

光标集成故障排除

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

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

   • Bash 脚本方法确保只有有效的 JSON-RPC 消息到达 Cursor

   • 在尝试连接之前，通过运行bun run build确保服务器已构建

2. 确保服务器正确地将 JSON-RPC 消息输出到标准输出：

   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. 尝试使用以下命令重建服务器：

   bun run build

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

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

1. 重启游标

2. 清除光标的缓存（帮助 > 开发者 > 清除缓存并重新加载）

3. 使用与 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（可选，用于更快的语音处理）

快速入门🚀

1. 克隆我的存储库：

2. 设置环境：

3. 配置您的设置：

• 使用你的 Home Assistant 详细信息编辑.env文件

• 必需：添加您的HASS_TOKEN （长期访问令牌）

4. 使用 Docker 构建并启动：

Docker 构建选项🐳

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

1. 标准构造

• 基本 MCP 服务器功能

• REST API 和 WebSocket 支持

• 无语音功能

2. 语音构建

• 包括唤醒词检测

• 语音转文本功能

• 拉取所需的图像：

  • onerahmet/openai-whisper-asr-webservice

  • rhasspy/wyoming-openwakeword

3. 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

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

发展💻

性能比较📊

文档📚

核心文档

• 配置指南

• API 文档

• 故障排除

高级功能

• 自然语言处理——人工智能驱动的自动化分析和控制

• 自定义提示指南- 创建和自定义 AI 行为

• 附加功能和工具- 附加实用程序和高级功能

客户端集成

光标集成🖱️

添加到.cursor/config/config.json ：

克劳德桌面💬

添加到您的 Claude 配置：

命令行💻

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

1. 进入scripts目录

2. 运行start_mcp.cmd

附加功能

语音功能🎤

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

• 🗣️ 唤醒词检测（“嘿贾维斯”，“ok google”，“alexa”）

• 🎯 使用快速耳语进行语音转文本

• 🌍 多语言支持

• 🚀 GPU 加速支持

语音功能设置

先决条件

1. 🐳 Docker 安装并运行

2. 🎮 带有 CUDA 的 NVIDIA GPU（可选）

3. 💾 4GB+ RAM（建议 8GB+）

配置

1. 在.env中启用语音：

2. 选择您的 STT 引擎：

可用型号🤖

根据您的需求选择：

• tiny.en ：最快，基本准确

• base.en ：良好的平衡（推荐）

• small.en ：准确度更高，但速度较慢

• medium.en ：高精度，资源密集型

• large-v2 ：准确率最高，但耗费资源

使用语音功能启动

额外工具🛠️

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

1. 家庭助理分析器 CLI （ ha-analyzer-cli.ts ）

   • 使用 AI 模型进行深度自动化分析

   • 安全漏洞扫描

   • 性能优化建议

   • 系统健康指标

2. 语音转文本示例（ speech-to-text-example.ts ）

   • 唤醒词检测

   • 语音到文本的转录

   • 多语言支持

   • GPU加速支持

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

这将：

1. 临时安装包

2. 使用 JSON-RPC 2.0 传输自动在 stdio 模式下运行

3. 创建用于日志记录的日志目录

4. 如果不存在，则创建默认的 .env 文件

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

与 Claude Desktop 集成

要将 MCP 与 Claude Desktop 结合使用：

1. 打开 Claude 桌面设置

2. 转到“高级”选项卡

3. 在“MCP 服务器”下，选择“自定义”

4. 输入命令： npx homeassistant-mcp

5. 点击“保存”

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

选项 2：本地安装

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

   USE_STDIO_TRANSPORT=true

2. 使用 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 消息格式

请求格式

响应格式

错误响应格式

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

支持的错误代码

与 Claude Desktop 集成

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

1. 创建或编辑您的 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

2. 添加 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" } } } }

3. 重新启动 Claude Desktop。

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

JSON-RPC 2.0 消息格式

用法

使用 NPX（最简单）

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

这将自动：

1. 以 stdio 模式启动服务器

2. 将 JSON-RPC 消息输出到 stdout

3. 将日志消息发送到 stderr

4. 如果日志目录不存在，则创建一个

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

手动安装

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

或者本地安装：

高级用法