reyhanfahlevi/homeassistant-mcp

开发工具

本页由 AI 翻译，技术细节请以原文为准。查看原文

0 stars 0 forks 质量 77 趋势 20MIT

Repository Install

Home Assistant REST API 的 MCP 服务器：状态、服务、历史、模板、事件。长寿命访问令牌。

概览

用于 Home Assistant REST API 的 MCP 服务器，通过长期访问令牌进行认证。 1. 在 Home Assistant 中：打开你的配置文件（http:// ：8123/profile）→ →。复制整个字符串。2. 将服务器添加到你的 MCP 客户端： HA_URL / HA_TOKEN 可作为别名使用。使用 http:// 和实例运行的端口（除非更改为 8123;在 Home Assistant OS 上为 80）。无需尾部斜杠。还没用npm——克隆、构建，并指向客户端文件夹： Node /absolute/path/to/homeassistant-mcp/dist/index.js 也能用。未直接覆盖的端点（/api/components、/api/events、/api/config/core/check_config 等）会经过ha_call_api，例如 {“method”： “GET”， “path”： “/api/components”}。 REST API 完全不涵盖：设备/区域/实体和长期统计数据。这些只存在于 WebSocket API 上——需要单独的服务器。

概述（AI 翻译）

用于 Home Assistant REST API 的 MCP 服务器，通过长期访问令牌进行认证。

布置

在 Home Assistant 中：打开你的个人资料（http:// :8123/profile）→ 长效访问令牌 → 创建令牌。复制整个字符串。
将服务器添加到你的 MCP 客户端：

[HA_URL / HA_TOKEN 可作为别名使用。使用 http:// 以及实例运行的端口（除非更改为 8123;在 Home Assistant OS 上为 80）。无需尾部斜杠。

来自本地结账处

还没用npm——克隆、构建，并指向客户端文件夹：

node /absolute/path/to/homeassistant-mcp/dist/index.js 也行。

工具

工具	类型	目的
`ha_get_config`	已读	实例配置：位置、单位、版本、组件
`ha_list_states`	已读	实体状态，经过`domain`过滤并分页
`ha_get_state`	阅读	一个实体的状态和属性
`ha_list_services`	阅读	可调用服务;与`domain`共计，其字段
`ha_get_history`	阅读	实体在一段时间内的状态历史
`ha_get_logbook`	已读	人类可读活动条目
`ha_get_error_log`	已读	当前会话的错误

本页由 AI 翻译，技术细节请以原文为准。

README

以下为原文 README 节选，完整内容请查看原文。

@reyhanfahlevi/homeassistant-mcp

MCP server for the Home Assistant REST API, authenticated with a long-lived access token.

Setup

In Home Assistant: open your profile (http://:8123/profile) → Long-Lived Access Tokens → Create Token. Copy the whole string.
Add the server to your MCP client:

{
  "mcpServers": {
    "homeassistant": {
      "command": "npx",
      "args": ["-y", "@reyhanfahlevi/homeassistant-mcp"],
      "env": {
        "HOMEASSISTANT_URL": "http://homeassistant.local:8123",
        "HOMEASSISTANT_TOKEN": "eyJhbGciOiJIUzI1NiIs..."
      }
    }
  }
}

HA_URL / HA_TOKEN are accepted as aliases. Use http:// and the port the instance runs on (8123 unless changed; 80 on Home Assistant OS). No trailing slash needed.

From a local checkout

Not on npm yet — clone, build, and point the client at the folder:

git clone https://github.com/reyhanfahlevi/homeassistant-mcp && cd homeassistant-mcp
npm install && npm run build

"command": "npx",
"args": ["-y", "/absolute/path/to/homeassistant-mcp"]

node /absolute/path/to/homeassistant-mcp/dist/index.js works too.

Tools

Tool	Type	Purpose
`ha_get_config`	read	Instance config: location, units, version, components
`ha_list_states`	read	Entity states, filtered by `domain` and paged
`ha_get_state`	read	One entity’s state and attributes
`ha_list_services`	read	Callable services; with `domain`, their fields
`ha_get_history`	read	State history of entities over a period
`ha_get_logbook`	read	Human-readable activity entries
`ha_get_error_log`	read	Errors from the current session
`ha_render_template`	read	Render a Jinja2 template server-side
`ha_list_calendars`	read	Calendar entities
`ha_get_calendar_events`	read	Events in a calendar between timestamps
`ha_call_service`	write	Control devices, e.g. `light` / `turn_on`
`ha_fire_event`	write	Fire an event on the event bus
`ha_set_state`	write	Overwrite an entity’s state (representation only, no device I/O)
`ha_delete_state`	destructive	Remove a manually created entity
`ha_call_api`	any	Any other path under `/api`

Endpoints not covered directly (/api/components, /api/events, /api/config/core/check_config, …) go through ha_call_api, e.g. {"method": "GET", "path": "/api/components"}.

Not covered by the REST API at all: the device/area/entity registries and long-term statistics. Those only exist over the WebSocket API — a separate server would be needed.

Development

npm install
npm run build              # tsc -> dist/
npm test                   # unit checks on the path/format helpers
npm run smoke              # boots dist/ over stdio and lists tools (+ live calls if env is set)

在 GitHub 查看完整 README

安装

npx -y @reyhanfahlevi/homeassistant-mcp

新手？先看 mcpskill.org 教程 →

配置

{
  "mcpServers": {
    "homeassistant": {
      "command": "npx",
      "args": ["-y", "@reyhanfahlevi/homeassistant-mcp"],
      "env": {
        "HOMEASSISTANT_URL": "http://homeassistant.local:8123",
        "HOMEASSISTANT_TOKEN": "eyJhbGciOiJIUzI1NiIs..."
      }
    }
  }
}