slhad-aha-mcp

AHA Model Context Protocol（MCP）服务

快速安装链接

STDIO

其他

无需 IDE 即可轻松测试

AHA 是 Another Home Assistant MCP Server 的缩写

此代码仓库实现了一个面向 Home Assistant 的 Model Context Protocol（MCP）服务，为 Home Assistant 与 MCP 客户端搭建桥梁。

使用此服务，你可以：

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

此服务支持多种传输方式：

• STDIO：传统的 MCP 客户端通信方式（默认）
• Server-Sent Events（SSE）：基于 Web 的实时通信
• Streamable HTTP：用于 Web 集成的基于 HTTP 的 MCP 通信

目录

• AHA Model Context Protocol（MCP）服务
  • 快速安装链接
  • AHA 是 Another Home Assistant MCP Server 的缩写
  • 目录
  • 动机
  • 功能
  • 可用工具
    • 生成工具文档
  • 项目结构
  • 示例：运行 MCP 服务
    • 1. 使用 STDIO 传输方式运行（默认）
    • 2. 使用 Server-Sent Events（SSE）传输方式运行
    • 3. 使用 Streamable HTTP 传输方式运行
    • 4. 快速启动 SSE 服务
    • 5. 使用 Podman/Docker 运行 - STDIO 传输方式
    • 6. 使用 Podman/Docker 运行 - HTTP/SSE 服务
    • 环境变量
  • 开始使用
    • 前置条件
    • 安装
    • 运行服务
    • 运行测试
    • Docker 用法
  • 贡献
  • 许可证

动机

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

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

本项目旨在通过提供可靠且功能完备的 MCP 服务、简便的 Docker 支持，并注重实际使用体验，来弥补这些不足。

特别说明： 本项目的大部分文档由 AI 生成或借助 AI 编写。由于这是一个副项目（尽管我的本职工作是开发者），我专注于构建有趣且可用的功能；如果生成的文档质量足够好，我更愿意审阅并采纳，而不是所有内容都亲自编写。

功能

• Home Assistant 客户端集成
• 实体注册表和管理
• 自动化和配置 MCP 端点
• Lovelace 仪表盘支持
• 多种传输方式：stdio、Server-Sent Events（SSE）和 Streamable HTTP
• 使用 Vitest 进行测试的 TypeScript 代码库
• 支持 Docker，便于部署

可用工具

此 MCP 服务提供了用于与 Home Assistant 交互的全面工具，包括：

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

⚠️ TOKEN 成本警告

**重要：**每个工具定义都会占用大模型上下文中的 token，即使未使用也一样！有些工具（例如 update-lovelace-config）单独就可能占用 4,000 多个 token。考虑排除不必要的工具，以尽量减少 token 消耗并提高对话效率。

如需查看所有可用工具及其详细说明和参数的完整列表，请参阅**工具文档**。

生成工具文档

工具文档由 MCP 服务自动生成：

npm run generate-docs

此命令将：

1. 使用 inspector 从 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. 使用 Server-Sent Events（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 客户端。对于只能通过基于工具的接口与服务交互，而不能通过通用资源查询进行交互的客户端或 Agent，这尤其有用。它使这类客户端能够发现并使用 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 连接：

• SSE："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

然后参阅：

• Stdio
• HTTP/SSE

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

• SSE："url": "http://localhost:3000/sse"
• HTTP："url": "http://localhost:8081/mcp"

贡献

欢迎提交拉取请求！对于重大更改，请先创建议题，讨论您希望进行的更改。

许可证

详情请参阅 LICENSE。