AI导哈

Home Assistant MCP服务器

AHA Model Context Protocol (MCP) Server是一个为Home Assistant设计的MCP服务器，提供Home Assistant与MCP客户端之间的桥梁，支持实体查询、状态更新、服务调用、自动化管理等功能，并支持多种传输方式。

  • by slhad
  • TypeScript
  • 混合部署
  • 更新于
在 GitHub 查看 slhad/aha-mcp

使用说明

AHA模型上下文协议（MCP）服务器

快速安装链接

STDIO（注：在中文语境中，STDIO通常直接保留原英文形式，不直接翻译，因为它是一个专业术语，指的是标准输入输出库。但若要解释其含义，可以表述为“标准输入输出（Standard Input and Output）”。）

其他

在没有IDE的情况下测试它相当有用

AHA代表另一个Home Assistant MCP服务器

这个仓库实现了Home Assistant的模型上下文协议（MCP）服务器，作为Home Assistant与MCP客户端之间的桥梁。

使用这台服务器，您可以：

  • 列出并查询Home Assistant实体（如灯光、传感器、开关等）
  • 检索并更新实体的状态
  • 调用Home Assistant服务（例如，打开/关闭设备）
  • 管理自动化：列出、创建、更新和验证自动化任务
  • 访问并更新实体注册表
  • 集成并更新Lovelace仪表板
  • 验证Home Assistant配置
  • 通过前缀或正则表达式搜索实体
  • 访问实体源和注册信息

该服务器支持多种传输方式：

  • **STDIO 翻译成中文是“标准输入输出（Standard Input and Output）”。**传统的MCP客户端通信（默认）
  • **服务器发送事件（SSE）**基于网络的实时通信
  • 可流式传输的HTTP基于HTTP的MCP通信，用于网页集成

目录

动机

在探索适用于Home Assistant的现有MCP服务器实现时，我发现：

  • 许多仓库并未提供可构建或运行的Docker镜像，这使得部署变得困难或无法进行。
  • 几个项目实际上并没有实现其README文件中描述的功能或协议。
  • 一些解决方案已经过时、无人维护，或者缺乏清晰的文档和测试覆盖率。

该项目旨在通过提供一个可靠且功能完备的MCP服务器，该服务器具备直观的Docker支持，并着重于实际应用中的可用性，来填补这些空白。

特别提及： 这个项目中的大部分文档都是由AI生成或辅助完成的。由于这是一个副业项目（尽管我是一名开发人员），我专注于构建有趣且实用的功能，并且更倾向于在生成的文档足够好时对其进行审查和接受，而不是手动编写所有内容。

特性/功能

  • Home Assistant 客户端集成
  • 实体注册与管理
  • 自动化配置MCP终端节点
  • Lovelace仪表板支持
  • 多种运输方式stdio，服务器发送事件（SSE），以及可流式传输的HTTP
  • 使用Vitest进行测试的TypeScript代码库
  • Docker 支持轻松部署

可用工具

这个MCP服务器提供 综合工具 用于与Home Assistant交互，包括：

  • 自动化管理创建、更新、删除和追踪自动化流程
  • 实体操作查询和操作Home Assistant实体
  • 服务调用执行Home Assistant服务
  • 配置验证并管理Home Assistant配置
  • 注册表访问访问实体和设备注册表
  • 配置条目流程辅助工具创建和管理Home Assistant集成流程

⚠️ 代币消耗警告

重要提示： 每个工具定义都会消耗您在大型语言模型（LLM）上下文中的标记，即使未使用也会如此！某些工具（如 update-lovelace-config) 仅这一步就可能消耗4000多个标记。考虑排除不必要的工具，以最大限度地减少标记消耗并提高对话效率。

如需查看所有可用工具的完整列表，以及详细的描述和参数，请参阅 工具文档。

生成工具文档

工具文档是从MCP服务器自动生成的：

npm run generate-docs

这个命令将会：

  1. 使用检查器从MCP服务器中提取所有可用工具
  2. 生成一个全面的Markdown文档文件（tools.md)
  3. 清理临时文件

注： 工具文档显示，服务器当前提供 39个工具 用于全面集成Home Assistant。

项目结构

  • src/ - 主源代码
    • hass/ - Home Assistant 客户端及辅助工具
    • server/ - MCP服务器实现
    • mcpTransports.ts - 传输层实现（HTTP，SSE）
  • tests/ - 测试文件和Home Assistant配置示例
  • scripts/ - 构建和文档生成脚本
  • Dockerfile - 支持容器化
  • package.json - 项目依赖项和脚本
  • tsconfig.json - TypeScript 配置
  • vitest.config.ts - Vitest 测试运行器配置

示例：运行MCP服务器

MCP服务器支持多种传输方法。您可以使用与您的（原系统/环境）相同的命令和参数结构来运行它 mcp_settings.json.

1. 使用STDIO传输运行（默认）

对于通过stdio进行的传统MCP客户端集成（服务器由MCP客户端启动）：

{
  "type": "stdio",
  "command": "tsx",
  "args": [
    "c:/dev/git/aha-mcp/src/index.ts"
  ],
  "env": {
    "LIMIT_RESOURCES": "-1",
    "RESOURCES_TO_TOOLS": "true",
    "DEBUG": "true",
    "HASS_URL": "https://your-home-assistant.local:8123",
    "HASS_ACCESS_TOKEN": "<your_token_here>"
  }
}

2. 使用服务器发送事件（SSE）传输运行

对于基于SSE的MCP通信，您需要单独运行服务器，然后配置MCP客户端以通过URL进行连接。

步骤1：启动SSE服务器

# Start the server with SSE transport using npm script
HASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:sse

# Or with additional configuration
RESOURCES_TO_TOOLS=true DEBUG=true HASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:sse

步骤2：配置MCP客户端以通过URL连接

{
  "url": "http://localhost:8081/sse",
  "alwaysAllow": [
    // your allowed tools here
  ]
}

3. 使用Streamable HTTP传输运行

对于基于HTTP的MCP通信，您需要单独运行服务器，然后配置MCP客户端以通过URL进行连接。

步骤1：启动HTTP服务器

# Start the server with streamable HTTP transport using npm script
HASS_URL=https://your-home-assistant.local:8123 HASS_ACCESS_TOKEN=<your_token_here> npm run start:local:http

步骤2：配置MCP客户端以通过URL连接

{
  "url": "http://localhost:8081/mcp",
  "alwaysAllow": [
    // your allowed tools here
  ]
}

4. 快速启动SSE服务器

使用npm脚本直接启动SSE服务器：

# Set your Home Assistant credentials first
export HASS_URL=https://your-home-assistant.local:8123
export HASS_ACCESS_TOKEN=<your_token_here>

# Start SSE server with RESOURCES_TO_TOOLS enabled
RESOURCES_TO_TOOLS=true DEBUG=true npm run start:local:sse

然后使用以下配置设置您的MCP客户端：

{
  "url": "http://localhost:3000/sse"
}

5. 使用 Podman/Docker 运行 - STDIO 传输

对于使用容器的STDIO传输：

{
  "type": "stdio",
  "command": "podman",
  "args": [
    "run",
    "-i",
    "--rm",
    "-e",
    "HASS_URL=https://your-home-assistant.local:8123",
    "-e",
    "HASS_ACCESS_TOKEN=<your_token_here>",
    "ghcr.io/slhad/aha-mcp:latest"
  ]
}

6. 使用 Podman/Docker 运行 - HTTP/SSE 服务器

对于HTTP/SSE传输，需在容器中单独运行服务器：

步骤1：启动服务器容器

# For SSE transport
podman run -p 8081:8081 -e HASS_URL=https://your-home-assistant.local:8123 -e HASS_ACCESS_TOKEN=<your_token_here> ghcr.io/slhad/aha-mcp -- sse

# For HTTP transport  
podman run -p 8081:8081 -e HASS_URL=https://your-home-assistant.local:8123 -e HASS_ACCESS_TOKEN=<your_token_here> ghcr.io/slhad/aha-mcp -- http

步骤2：配置MCP客户端

{
  "url": "http://localhost:3000/sse",  // for SSE
  // or
  "url": "http://localhost:3000/mcp"   // for HTTP
}

替换 <your_token_here> 使用您实际的Home Assistant访问令牌。

环境变量

以下环境变量可以设置以配置MCP服务器：

  • HASS_URL （必填）：您的Home Assistant实例的URL。示例： https://your-home-assistant.local:8123 （代码中的默认值： http://localhost:8123）
  • HASS_ACCESS_TOKEN （必填）：用于Home Assistant的长期访问令牌。没有此令牌，服务器将无法启动。
  • DEBUG设置为 true 启用调试日志记录。默认： false。
  • RESOURCES_TO_TOOLS设置为 true 以便将映射资源分配给工具。默认： false。
    • 详细解释： 当启用此选项时，它会将Home Assistant的资源（如实体、自动化和服务）作为单独的工具暴露给MCP客户端。这对于只能通过基于工具的接口与服务器交互的客户端或代理特别有用，而不是通过通用的资源查询。这使得此类客户端能够发现并使用Home Assistant的特性作为独立、可调用的工具，从而提高了工具受限环境下的兼容性和可用性。
  • LIMIT_RESOURCES设置一个数字以限制服务器返回的资源数量。默认：无限制。

注： 服务器传输方法现在由命令行参数控制（sse 或者 http）而不是环境变量。

入门指南

先决条件

  • Node.js（建议使用v18+版本）
  • Docker（可选，用于容器化部署）

安装

npm install

运行服务器

对于STDIO传输（由MCP客户端启动）：

# Set environment variables and run with npm
npm start

对于HTTP/SSE传输（需单独运行服务器）：

# Run SSE server on port 8081
npm run start:local:sse

# Run HTTP server on port 8081:8081
npm run start:local:http

# Quick SSE server startup with environment variables
RESOURCES_TO_TOOLS=true DEBUG=true npm run start:local:sse

然后配置您的MCP客户端以通过URL进行连接：

  • 上海证券交易所 "url": "http://localhost:3000/sse"
  • HTTP：（超文本传输协议） "url": "http://localhost:8080/mcp"

运行测试

npm run test:short

注： 当前的单元测试是在真实的Home Assistant实例上运行的，尚未使用模拟数据。这意味着测试需要一个正在运行的Home Assistant服务器以及有效的凭据才能成功执行。

Docker 使用方法

在Docker容器中构建并运行服务器：

# Build the container
npm run docker

然后接着：

对于HTTP/SSE模式，请使用相应的URL配置您的MCP客户端：

  • 上海证券交易所 "url": "http://localhost:3000/sse"
  • HTTP： "url": "http://localhost:8081/mcp"

做出贡献

欢迎提交拉取请求！对于重大更改，请先打开一个议题进行讨论，说明您希望做出的更改。

许可证

看 许可证 详情如下。

相关 MCP