ha-mcp

关键词

家庭自动化WebSocket 服务后端资源管理模型上下文与 AI 集成

【使用说明】

  • 项目简介

    • ha-mcp 是一个完整的 MCP 服务器实现，提供面向 LLM 客户端的上下文服务能力，能够托管资源、注册与执行工具，以及定义和渲染提示模板。服务器通过 WebSocket（作为主通道）与 REST API 提供资源访问、工具执行和提示渲染等能力，并支持会话管理、能力声明和多种传输协议。

  • 主要功能点

    • 提供资源管理与数据访问能力，便于 LLM 客户端获取 Home Assistant 的状态、配置、日志等信息。
    • 注册和执行工具，覆盖实体状态、历史、服务调用、配置清单、辅助工具（输入项、计时器、脚本、场景、注册表等）等多种 Home Assistant 功能。
    • 提供 Prompt 模板渲染能力，支持将动态上下文渲染为自然语言或结构化输出。
    • 通过 WebSocket 作为主通信通道，REST API 负责脚本、场景、自动化等 CRUD 操作以及一些只适合 REST 的任务。
    • 支持自动重连、请求重试、缓存静态数据、健康检查等运维能力，确保与 Home Assistant 的稳定对接。
    • 具备会话管理与能力声明，客户端可根据 MCP 的能力进行对话设计和能力调度。

  • 安装步骤

    • 直接使用发布的二进制包或自行从源码构建二进制文件，然后运行 ha-mcp 即可。
    • 也可以在 Docker 环境中运行，按 Release 页的镜像标签拉取对应版本，环境变量可用于配置 Home Assistant 连接、Token、端口等。
    • 运行前，请确保 Home Assistant WebSocket API 可达，且具备长期访问令牌。

  • 服务器配置（给 MCP 客户端的配置信息）

    • 说明：MCP 客户端需要知道服务器的启动命令（command）及参数（args），以便启动 MCP 服务器并连接。
    • 配置示例（JSON，字段含义已注释）： { "servers": { "ha-mcp": { "name": "ha-mcp Home Assistant MCP Server", // 服务器名称，标识该 MCP 服务 "command": "ha-mcp", // 启动命令，运行 MCP 服务器二进制 "args": [ "--ha-url", "http://homeassistant.local:8123", // Home Assistant 的 URL（WebSocket 地址会自动转换） "--ha-token", "<your-long-lived-access-token>", // 与 Home Assistant 认证的令牌 "--port", "8080" // MCP 服务器侦听端口 ] } } }

    说明要点

    • server.url/ha-url 指向 Home Assistant 实例（使用 WebSocket 连接）；
    • token 用于 Home Assistant 认证，若客户端提供 Authorization 头，也可以覆盖默认 token；
    • 端口用于 MCP 服务器对外监听，默认常见端口可自定义。
    • 该配置仅用于 MCP 客户端启动服务器时的参数；实际 MCP 请求会使用服务器对外提供的地址端口。

  • 基本使用方法

    • 启动服务器后，客户端通过 MCP 协议（JSON-RPC 之类的请求）向 ha-mcp 发送请求以读取资源、调用工具、获取 Prompts 等。
    • 使用示例（简要说明，不包含具体代码）：
      • 启动并监听后，客户端通过配置的服务器地址和鉴权信息建立连接；
      • 客户端可以通过注册的工具名来调用 Home Assistant 的功能，如查询状态、执行服务、获取历史、渲染模板等；
      • 客户端可通过提示模板渲染来获取可用于对话的上下文信息，提升交互质量；
      • 若网络波动，Ha-MCP 会自动重连并重试请求。

  • 运行与调试建议

    • 启用 debug 日志以便排查连接、鉴权、请求和重试等问题；
    • 如果使用反向代理，请确保 WebSocket upgrade 配置正确；
    • 关注健康检查与缓存 TTL 设置，确保性能与稳定性。

服务器信息

访问项目