HA Claude Assistant MCP Server

使用说明（Markdown 格式）

• 项目简介

  • 这是一个完整的 MCP 服务器实现，能够通过 MCP 标准将 Home Assistant 的资源（实体）、工具（如列出实体、读取状态、调用服务、排程管理）以及提示模板对外暴露，LLM 客户端可通过 JSON-RPC 调用进行读取、执行和渲染。

• 主要功能点

  • MCP 服务端实现：实现 MCP 协议的 ListTools 和 CallTool 请求处理，返回工具清单与执行结果。
  • 暴露工具集：list_entities、get_state、call_service、manage_schedule 等工具，配合 HAClient 调用 Home Assistant APIs。
  • Home Assistant 集成：通过 HAClient 封装对 HA 的 REST API 调用，包含状态获取、实体列表、服务调用、配置获取等。
  • 运行模式与传输：通过 StdioTransport 提供服务器与 Claude Code 等 MCP 客户端的通信；整合 CLI、Slack、MCP 等多种接口。
  • 安全与稳健性：对 HA 连接进行自适应连接、错误处理与日志输出，具备对工具执行的错误返回。

• 安装步骤

  • 准备 Node.js 环境
  • 安装依赖并构建：
    • npm install
    • npm run build
  • 启动 MCP 服务器（示例路径，实际以构建产物为准）：
    • node dist/interfaces/mcp-server.js
  • 服务器启动后，MCP 客户端（如 Claude Code）即可通过配置连接并使用工具

• 服务器配置（MCP 客户端需要的连接信息） 注：以下 JSON 配置用于 Claude Code 等 MCP 客户端的 mcpServers 设置，描述的是如何启动并连接到本 MCP 服务器。请将 serverName、命令路径和参数替换为你的环境实际值。

  { "ha-assistant": { "name": "ha-assistant", "command": "node", "args": ["dist/interfaces/mcp-server.js"], "env": { "HA_URL": "http://your-ha-ip:8123", "HA_TOKEN": "your_long_lived_access_token" } } }

  说明:

  • ha-assistant 为在 MCP 客户端中配置的服务器名称，可自定义。命令为启动服务器的命令，args 为启动参数，dist/interfaces/mcp-server.js 为本仓库构建后的入口文件路径（需按实际构建产物路径调整）。
  • env 中的 HA_URL 与 HA_TOKEN 用于 Home Assistant 的连接认证，替换为你实际的 Home Assistant 地址与长久性访问令牌。
  • 以上配置仅用于 MCP 客户端连接服务器，MCP 客户端本身不需要额外的实现代码。

• 基本使用方法

  • 构建并启动 MCP 服务器后，在 MCP 客户端（如 Claude Code）配置好连接信息即可使用。
  • 客户端发起请求时，LLM 将通过 MCP 调用以下工具：list_entities、get_state、call_service、manage_schedule，服务器将返回标准化的 JSON-RPC 响应或文本内容。
  • 结合 Home Assistant 的 API，支持读取实体、执行服务、管理排程等常用场景。