Home Assistant MCP Server

hass-mcp-server

用于全面控制 Home Assistant 的 MCP 服务。AI Agent（GitHub Copilot、Claude 等）可以管理您的仪表板、自动化、文件、应用、实体等，让您无需亲自操作 HA 设置。

功能

• 仪表板管理 — 创建、更新、删除 Lovelace 仪表板，并部署完整的仪表板配置
• 文件管理 — 通过 SFTP 在您的 HA 实例上上传、读取、列出和删除文件（例如自定义卡片、图片、HTML 文件）
• 自动化、脚本、场景 — 对自动化、脚本和场景执行完整的增删改查操作
• 输入辅助工具 — 创建和管理 input_boolean、input_number、input_text、input_select、input_datetime、input_button、counter 和 timer 辅助工具
• 应用管理 — 安装、启动、停止、重启、卸载和配置应用（附加组件）
• 实体与服务控制 — 查询状态、调用服务、渲染模板、浏览实体／设备／区域注册表
• 系统工具 — 系统信息、配置验证、备份、重启核心、错误日志
• 事件与日历工具 — 列出事件类型、触发事件、查询日历

66 个工具，分为 5 个类别，使用 HA 的三种传输层：REST API、WebSocket API 和 SSH/SFTP。

前提条件

• Home Assistant OS（或任何带有 Supervisor 的 HA 安装）
• 长期有效访问令牌 — 在 HA → 个人资料 → 安全 → 长期有效访问令牌中创建
• Node.js 20+
• （可选）SSH 应用 — 仅文件管理工具需要。从应用商店安装“Advanced SSH & Web Terminal”。

快速开始

无需安装 — MCP 客户端会通过 npx 自动运行服务。只需将配置添加到客户端，即可开始使用。

配置

服务通过 MCP 客户端配置文件中的环境变量进行配置。客户端会在启动时将这些变量注入服务进程 — 无需设置系统级环境变量。

必需变量

变量	说明	示例
HA_URL	Home Assistant 基础 URL	http://homeassistant.local:8123
HA_TOKEN	长期访问令牌	（来自 HA 个人资料 → 安全）

可选变量（用于文件管理）

文件管理工具需要 SSH 访问权限。请参阅下方的设置 SSH。

变量	说明	示例
HA_SSH_HOST	SSH 主机名	homeassistant.local
HA_SSH_PORT	SSH 端口（默认：22）	22
HA_SSH_USER	SSH 用户名（必须为 root）	root
HA_SSH_KEY_PATH	SSH 私钥路径	请参阅各操作系统的示例
HA_SSH_PASSWORD	SSH 密码（可替代密钥）	（你的密码）

获取长期访问令牌

1. 打开 Home Assistant 界面
2. 点击个人资料图标（左下角）
3. 在“安全”选项卡下滚动到长期访问令牌
4. 点击创建令牌，为其命名并复制令牌

MCP 客户端设置

选择适用于你的 MCP 客户端的设置方式。无论选择哪种方式，添加配置后，客户端都会通过 npx 自动下载并运行服务。

提示： 如果不需要文件管理工具，可以省略 HA_SSH_* 变量。服务会在不启用 SFTP 的情况下启动，只有尝试使用文件工具时才会失败。

VS Code（GitHub Copilot）

选项 A：安装扩展（推荐）

最简单的方式 — 从 VS Code Marketplace 安装 Home Assistant MCP Server 扩展。它会自动注册 MCP 服务并安全存储你的凭据。

1. 从 Marketplace 安装扩展（或在“扩展”视图中搜索 “Home Assistant MCP Server”）。
2. 在“设置”中设置 Home Assistant URL → homeAssistantMcp.url。
3. 从命令面板（Ctrl+Shift+P）运行 "Home Assistant MCP: Set Access Token"。
4. MCP 服务会自动显示在 Copilot Chat 中。

如需使用文件管理功能，请配置 SSH 设置（homeAssistantMcp.ssh.*），并可选择运行 "Home Assistant MCP: Set SSH Password"。

选项 B：通过 mcp.json 一键安装

点击本 README 顶部的徽章，或使用下方链接。VS Code 会提示你输入 Home Assistant URL 和访问令牌。

选项 C：手动设置 mcp.json

在工作区中创建 .vscode/mcp.json（或将配置添加到用户设置中以供全局使用）：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ha-url",
      "description": "Home Assistant base URL (e.g. http://homeassistant.local:8123)"
    },
    {
      "type": "promptString",
      "id": "ha-token",
      "description": "Home Assistant long-lived access token",
      "password": true
    }
  ],
  "servers": {
    "home-assistant": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jarahkon/hass-mcp-server@latest"],
      "env": {
        "HA_URL": "${input:ha-url}",
        "HA_TOKEN": "${input:ha-token}"
      }
    }
  }
}

启用 SSH（用于文件管理工具）：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ha-url",
      "description": "Home Assistant base URL (e.g. http://homeassistant.local:8123)"
    },
    {
      "type": "promptString",
      "id": "ha-token",
      "description": "Home Assistant long-lived access token",
      "password": true
    }
  ],
  "servers": {
    "home-assistant": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jarahkon/hass-mcp-server@latest"],
      "env": {
        "HA_URL": "${input:ha-url}",
        "HA_TOKEN": "${input:ha-token}",
        "HA_SSH_HOST": "homeassistant.local",
        "HA_SSH_USER": "root",
        "HA_SSH_KEY_PATH": "/home/you/.ssh/ha_ed25519"
      }
    }
  }
}

Claude Desktop

编辑 Claude Desktop 配置文件：

OS	配置文件路径
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "home-assistant": {
      "command": "npx",
      "args": ["-y", "@jarahkon/hass-mcp-server@latest"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your_long_lived_access_token_here"
      }
    }
  }
}

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "home-assistant": {
      "command": "npx",
      "args": ["-y", "@jarahkon/hass-mcp-server@latest"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your_long_lived_access_token_here"
      }
    }
  }
}

其他 MCP 客户端

任何支持 stdio 服务的 MCP 客户端都可使用。将 npx 用作命令，并将 -y @jarahkon/hass-mcp-server@latest 作为参数，然后在 env 区块中传入 HA_URL 和 HA_TOKEN。

设置 SSH（用于文件管理）

文件管理工具（ha_upload_file、ha_read_file、ha_list_files 等）需要 SSH 访问您的 Home Assistant 实例。

1. 在 Home Assistant 中安装 SSH 应用

1. 在 HA 中，前往 设置 → 应用 → 应用商店
2. 安装 Advanced SSH & Web Terminal
3. 在应用配置中，将用户名设为 root（SFTP 所必需），并启用 sftp: true
4. 配置身份验证——设置密码或将您的公钥添加到 authorized_keys（推荐）
5. 启动应用并检查日志，确认其已成功启动

2. 生成 SSH 密钥（推荐）

基于密钥的身份验证比密码更安全。

# Generate a key pair (leave passphrase empty for automated use)
ssh-keygen -t ed25519 -f ~/.ssh/ha_ed25519 -C "ha-mcp-server"

这会创建 ~/.ssh/ha_ed25519（私钥）和 ~/.ssh/ha_ed25519.pub（公钥）。

将公钥内容添加到 HA 中的应用配置：

ssh:
  username: root
  password: ""
  authorized_keys:
    - "ssh-ed25519 AAAA...contents of ha_ed25519.pub..."
  sftp: true

3. 在 MCP 客户端配置中添加 SSH 变量

在 MCP 客户端配置 env 区块中，将以下环境变量与 HA_URL 和 HA_TOKEN 一同添加：

"HA_SSH_HOST": "homeassistant.local",
"HA_SSH_USER": "root",
"HA_SSH_KEY_PATH": "/home/you/.ssh/ha_ed25519"

或者使用密码身份验证：

"HA_SSH_HOST": "homeassistant.local",
"HA_SSH_USER": "root",
"HA_SSH_PASSWORD": "your_ssh_password_here"

SSH 密钥路径示例

OS	HA_SSH_KEY_PATH 示例
Windows	C:/Users/you/.ssh/ha_ed25519
macOS	/Users/you/.ssh/ha_ed25519
Linux	/home/you/.ssh/ha_ed25519

工具参考

仪表盘（6 个工具）

工具	描述
ha_list_dashboards	列出所有 Lovelace 仪表盘
ha_create_dashboard	使用 url_path、title、icon 创建新仪表盘
ha_update_dashboard	更新仪表盘属性（title、icon、侧边栏可见性）
ha_delete_dashboard	按 ID 删除仪表盘
ha_get_dashboard_config	获取仪表盘的完整 Lovelace 配置 JSON
ha_save_dashboard_config	将完整的 Lovelace 配置部署到仪表盘

文件（7 个工具）— 需要 SSH

工具	描述
ha_list_files	列出 HA 上某个目录中的文件（相对于 /config/）
ha_read_file	读取 HA 上的文件内容
ha_upload_file	通过 SFTP 将本地文件上传到 HA
ha_upload_file_content	将字符串内容直接写入 HA 上的文件
ha_delete_file	删除 HA 上的文件（仅限安全目录）
ha_mkdir	在 HA 上创建目录
ha_file_exists	检查 HA 上的文件或目录是否存在

自动化、脚本、场景与助手（17 个工具）

工具	描述
ha_list_automations	列出所有自动化
ha_get_automation	按 ID 获取指定自动化的配置
ha_create_automation	创建新的自动化
ha_update_automation	更新现有自动化
ha_delete_automation	删除自动化
ha_list_scripts	列出所有脚本
ha_create_script	创建新脚本
ha_update_script	更新现有脚本
ha_delete_script	删除脚本
ha_list_scenes	列出所有场景
ha_create_scene	创建新场景
ha_update_scene	更新现有场景
ha_delete_scene	删除场景
ha_list_helpers	列出所有输入助手（布尔值、数字等）
ha_create_helper	创建任意类型的输入助手
ha_update_helper	更新现有助手
ha_delete_helper	删除助手

应用与系统（18 个工具）

工具	描述
ha_list_addons	列出所有已安装应用及其状态
ha_addon_info	获取特定应用的详细信息
ha_install_addon	按 slug 安装应用
ha_start_addon	启动应用
ha_stop_addon	停止应用
ha_restart_addon	重启应用
ha_uninstall_addon	卸载应用
ha_addon_options	获取或设置应用配置选项
ha_system_info	获取系统信息（core、OS、supervisor、主机）
ha_check_config	重新加载前验证 HA 配置
ha_create_backup	创建完整或部分备份
ha_list_backups	列出所有备份
ha_restart_core	重启 Home Assistant core
ha_check_api	检查 HA API 是否可访问并正常响应
ha_get_config	获取 HA 配置（位置、单位、版本、组件）
ha_update_core_config	更新 core 配置（内部/外部 URL、位置、单位）
ha_get_components	列出所有已加载的 HA 集成/组件
ha_get_error_log	获取 Home Assistant 错误日志内容

实体与服务（18 个工具）

工具	描述
ha_get_states	获取所有实体状态（可按域筛选）
ha_get_entity	获取特定实体的完整状态和属性
ha_call_service	调用任意 HA 服务（turn_on、turn_off、notify 等）
ha_list_services	按域列出可用服务
ha_render_template	渲染 Jinja2 模板
ha_list_entity_registry	列出实体注册表中的实体
ha_list_devices	列出所有设备
ha_list_areas	列出所有区域（房间）
ha_create_area	创建新区域
ha_get_history	获取实体在一段时间内的状态历史
ha_get_logbook	获取日志簿条目（活动日志），可按实体筛选
ha_get_events	列出所有可用事件类型
ha_fire_event	触发自定义事件以启动自动化
ha_set_state	设置或创建实体状态（虚拟传感器、覆盖值）
ha_delete_state	删除实体状态
ha_get_calendars	列出所有日历实体
ha_get_calendar_events	获取特定日历中的事件
ha_handle_intent	处理对话/语音意图

架构

该服务使用三种传输层与 Home Assistant 通信：

层	用途	库
REST API（/api/...）	服务调用、状态、历史记录、模板、Supervisor 代理、自动化/脚本/场景的 CRUD 操作	内置 fetch
WebSocket API（/api/websocket）	仪表板 CRUD 操作、辅助项 CRUD 操作、实体注册表	ws
SSH/SFTP	在 HA 文件系统上上传/下载/列出/删除文件	ssh2-sftp-client

src/
├── index.ts              # MCP server entry point, registers all tools
├── config.ts             # Environment variable parsing and validation
├── ha/
│   ├── rest-client.ts    # REST API client with auth header
│   ├── ws-client.ts      # WebSocket client with auto-reconnect
│   └── sftp-client.ts    # SFTP client with path safety checks
└── tools/
    ├── dashboards.ts     # 6 dashboard tools
    ├── files.ts          # 7 file management tools
    ├── automations.ts    # 17 automation/script/scene/helper tools
    ├── addons.ts         # 18 app and system tools
    └── entities.ts       # 18 entity and service tools

vscode-extension/         # VS Code Marketplace extension wrapper
└── src/
    └── extension.ts      # Registers MCP server via mcpServerDefinitionProviders API

安全注意事项

• SFTP 路径限制：允许在 /config/ 下的任意位置执行读取操作。写入和删除操作仅限于安全子目录（www/、custom_components/、themes/、blueprints/、scripts/、automations/）和指定文件（configuration.yaml、automations.yaml、scripts.yaml、scenes.yaml）。禁止对 deps/ 或 .storage/ 等系统目录执行写入操作。
• 令牌安全：切勿提交 .env 文件。.gitignore 已将其排除。
• SSH 身份验证：优先使用基于 SSH 密钥的身份验证（HA_SSH_KEY_PATH），而不是密码。切勿将私钥或密码提交到源代码管理中。

许可证

MIT