Claude Home Assistant MCP 服务器

关键词

Home AssistantClaude Code自动化助手本地服务器API 集成

使用说明（Markdown格式）

  • 项目简介

    • 该仓库实现了一个基于 MCP（Model Context Protocol）的服务器端，内置 13 个针对 Home Assistant 的工具，能够让 LLM 客户端通过 MCP 协议访问 Home Assistant 的资源、调用服务、获取历史与日志等信息，并可通过 STDIO 形式与 Claude Code 等客户端集成使用。

  • 主要功能点

    • ha_get_entities: 列出实体及其状态，可按域过滤，支持返回实体标识、状态与友好名。
    • ha_get_entity_state: 获取指定实体的详细状态与属性、最后变更时间等。
    • ha_call_service: 调用 Home Assistant 服务，支持目标实体/区域/设备与数据载荷。
    • ha_get_areas: 列出区域/区域内实体计数。
    • ha_get_devices: 列出设备，可按区域过滤。
    • ha_get_automations: 列出自动化及其状态、上次触发时间等。
    • ha_get_integrations: 列出已安装的集成/组件。
    • ha_restart: 重启 Home Assistant Core（需要确认）。
    • ha_reload_config: 重载指定配置域（不重启）。
    • ha_get_logs: 获取最近的日志以协助调试。
    • ha_get_history: 获取实体在一段时间内的历史状态。
    • ha_fire_event: 触发自定义事件以触发自动化等行为。
    • ha_render_template: 在 HA 上下文中渲染 Jinja2 模板。
    • 以上工具通过 HA REST API 和 Supervisor API 与 Home Assistant 进行交互，输出格式适合直接在 MCP 客户端进行展示与解析。

  • 安装步骤

    • 获取代码与依赖：将仓库中的 MCP 服务器代码获取到本地环境，并安装所需依赖（如 Node.js、TypeScript/编译工具等）。
    • 构建/运行：将 TypeScript 代码编译为可执行的 JS 入口后，通过 MCP 客户端以 STDIO 传输方式启动服务器。服务器设计为通过标准输出/输入与客户端进行 JSON-RPC 交互。
    • 环境配置：若使用 HA Supervisor API，需要设置 SUPERVISOR_TOKEN 等环境变量（如在 ha-client.ts 中所需）。确保服务器可访问 Home Assistant 的 REST API 与 Supervisor API。
    • 启动方式：以 MCP 客户端要求的方式启动并将该 MCP 服务器进程连接到客户端，确保 STDIO 通道可用。

  • 服务器配置（示例，JSON 格式，非代码块呈现） { "server_name": "claude-home-assistant", "command": "node", "args": ["path/to/your/built/entry/index.js"], "workdir": "/path/to/your/工作目录", "env": { "SUPERVISOR_TOKEN": "<请填写在 Home Assistant 中获取的 Token（可选，若使用 Supervisor API 需要>", "HA_API_BASE": "http://supervisor/core/api", "SUPERVISOR_API_BASE": "http://supervisor" } // 备注：MCP 客户端将通过 STDIO 连接该服务器，服务器名称与版本信息可在启动时暴露给客户端。 }

  • 基本使用方法

    • 启动：按照 MCP 客户端要求，将服务器作为一个 STDIO MCP 服务启动，确保服务器能通过 STDIO 与 Claude Code 等客户端通信。
    • 调用工具：通过 MCP 客户端的对话/调用界面，向服务器发送请求以执行上述工具（如查询实体、调用服务、获取历史等），获得结构化的 JSON-RPC 响应并在客户端展示。
    • 认证与权限：若需要访问 HA 的 REST/Supervisor API，请正确配置 SUPERVISOR_TOKEN，确保服务器具备对应权限。
    • 监控与日志：使用 ha_get_logs、ha_get_entities 等工具获取诊断信息，帮助排错与验证配置。

  • 备注

    • 该实现通过 Node.js/TypeScript 编写，运行时作为 MCP 服务器，强调“标准化上下文提供与工具执行”能力，方便与 LLM 客户端进行交互式对话与自动化集成。

服务器信息

访问项目