ha-mcp - MCP 服务器

关键词

Home AssistantJSON-RPCWebSocket服务编排自动化集成

使用说明（Markdown 格式）

  • 项目简介

    • ha-mcp 是一个基于 MCP（Model Context Protocol）的服务器实现，旨在为 AI 助手提供对 Home Assistant 的上下文信息、操作工具以及可定制的提示模板。通过 JSON-RPC 形式与客户端通信，支持会话管理、能力声明以及对多种传输协议的支持，提供稳定、安全、可扩展的上下文服务框架。

  • 主要功能点

    • MCP 核心能力
      • 资源管理：向 LLM 客户端提供可访问的数据资源（如 HA 的实体、日志、配置等）入口。
      • 工具注册与执行：注册多达数十种工具，允许 LLM 触发 HA 的操作（如查询实体、创建/修改用例、查询日志、调用服务等）。
      • Prompt 模板：支持 Prompts 的定义与渲染，便于实现对话式交互和模板化输出。
      • 会话及能力声明：服务端管理会话、能力范围及访问控制。
    • 传输与协议
      • WebSocket 为主通道，提供状态查询、服务调用、注册/执行工具等能力。
      • REST API 提供对 Automations、Scripts、Scenes 等对象的 CRUD 等功能（部分在示例实现中作为替代／后备路径）。
      • 通过 JSON-RPC 进行请求/响应的标准化封装，便于与不同的 LLM 客户端对接。
    • 安全与扩展性
      • 读写权限控制、IP 白/黑名单、逐工具粒度控制等访问控制策略。
      • 会话管理与自动重连机制，确保在网络波动下恢复可靠性。
      • 可通过插件式工具注册与工具过滤系统，灵活控制可用操作集合。

  • 安装步骤

    • 自行编译
      • 依赖条件：Go 1.26 及以上
      • 构建命令：go build -o ha-mcp ./cmd/ha-mcp
    • 运行
      • 启动方式示例（最常用参数）： ha-mcp --ha-url http://homeassistant.local:8123 --ha-token YOUR_LONG_LIVED_TOKEN --port 8080
      • 也可先初始化配置并再启动： ha-mcp init ha-mcp
    • 运行环境
      • Docker 镜像也可用于快速部署，环境变量可结合 docs/configuration.md 的说明进行设置（如 HA 地址、令牌、端口、HTTPS/WSS 等）。
    • 连接客户端配置
      • MCP 客户端连接服务器时需使用 JSON 配置，指定服务器类型、URL、认证信息等。示例（JSON，供客户端使用，解释见下方“服务器配置”）： { "server_name": "ha_home", "command": "./ha-mcp", "args": ["--ha-url", "http://homeassistant.local:8123", "--ha-token", "<your-long-lived-token>", "--port", "8080"] }
      • 注：以上配置仅代表服务器启动参数，客户端使用时不需要包含令牌等敏感信息。

  • 服务器配置（供 MCP 客户端参考，用于启动和连接服务器） 配置示例（JSON，便于理解和操作，非实际代码块格式）： { "server_name": "ha_home", "command": "./ha-mcp", "args": [ "--ha-url", "http://homeassistant.local:8123", "--ha-token", "<你的长时效访问令牌>", "--port", "8080" ] } 配置字段说明

    • server_name：服务器的逻辑名称，用于区分不同 MCP 服务器实例。
    • command：启动 MCP 服务器的可执行文件路径（相对路径或绝对路径）。
    • args：启动命令的参数数组，常用参数包括：
      • --ha-url：Home Assistant 的地址，确保 MCP 服务器能连接到 HA 的 API。
      • --ha-token：用于访问 Home Assistant 的长时效访问令牌（Token），请妥善保管，不要暴露。
      • --port：MCP 服务器监听端口，默认可设为 8080。 注意事项
    • 客户端连接时需要能访问到 MCP 服务器的地址与端口，确保网络连通性。
    • 生产环境建议通过 HTTPS/WSS、证书与鉴权等安全机制保护通信。

  • 基本使用方法

    • 启动后，向 LLM 客户端暴露的 API 将提供对 Home Assistant 的上下文信息、工具执行以及模板渲染能力。
    • LLM 客户端通过 MCP 客户端集成（如 Claude、OpenAI 插件等）配置，指向该 MCP 服务器节点，并使用服务器提供的资源、工具与 Prompt 来组织对话和任务执行。
    • 常见操作场景包括：查询 HA 实体状态、创建/修改自动化、执行脚本/场景、渲染模板、以及通过服务调用实现自动化联动。
    • 如需对可用功能进行细粒度控制，可在服务器配置中设置工具白/黑名单、只读模式等参数。

  • 运行与扩展建议

    • 按照仓库 README/NODE 文档的指引，结合 CI/CD、lint 和集成测试，确保在本地/云环境中稳定运行。
    • 如需自定义工具、Prompts 或资源，请使用注册与过滤机制进行扩展和授权控制。

  • 备注

    • 本实现包含完整的服务端逻辑与测试用例，覆盖 MCP 核心能力、工具注册、权限控制、会话管理以及与 Home Assistant 的集成路径。你可以基于此进一步扩展工具集、改造认证策略，或扩展传输协议与前端客户端的接入方式。

服务器信息

访问项目