Home Assistant MCP Server
io.github.jarahkon由 GitHub 账号 jarahkon 发布v1.0.6更新于 Oct 24, 2026
MCP server for full Home Assistant control — dashboards, files, automations, add-ons, and more
概览
本地 MCP 服务器,让助手全面控制 Home Assistant:仪表板、自动化、文件、应用、实体与服务。
- 可以做什么
- 列出、创建、更新、删除 Lovelace 仪表板并部署完整配置
- 通过 SFTP 上传、读取、列出、创建和删除 HA 实例上的文件
- 对自动化、脚本、场景和输入辅助元素进行完整的增删改查
- 安装、启动、停止、重启、卸载和配置应用,并查看系统信息、校验配置、备份、重启核心和读取错误日志
- 查询实体状态、调用服务、渲染模板、浏览实体/设备/区域注册表、读取历史与日志、触发事件、设置状态和查询日历
- 适用场景
- 适合希望让助手代为搭建或修改 Home Assistant 仪表板、编写自动化与脚本、查看实体状态与历史,或管理应用和备份,而不必自己在 HA 界面中逐项操作的场景。
- 运行要求
- 通过 npx 在本地运行,需要 Node.js 20+。需要带 Supervisor 的 Home Assistant 安装、HA_URL 基础地址,以及 HA_TOKEN 中的长期访问令牌。文件工具还需安装 Advanced SSH & Web Terminal 应用并启用 SFTP,并配置 HA_SSH_HOST、HA_SSH_USER(root)以及 HA_SSH_KEY_PATH 或 HA_SSH_PASSWORD 之一。
安装
在 SourceWeft 中
- 打开 控制台中的 Home Assistant MCP Server,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
hass-mcp-server
[npm version] [CI] [License: MIT]
MCP server for full Home Assistant control. AI agents (GitHub Copilot, Claude, etc.) can manage your dashboards, automations, files, apps, entities, and more — so you never have to touch HA settings yourself.
[Install VS Code Extension] [Install in VS Code] [Install in VS Code Insiders]Features
- Dashboard management — Create, update, delete Lovelace dashboards and deploy full dashboard configs
- File management — Upload, read, list, and delete files on your HA instance via SFTP (e.g. custom cards, images, HTML files)
- Automations, scripts, scenes — Full CRUD for automations, scripts, and scenes
- Input helpers — Create and manage input_boolean, input_number, input_text, input_select, input_datetime, input_button, counter, and timer helpers
- App management — Install, start, stop, restart, uninstall, and configure apps (add-ons)
- Entity & service control — Query states, call services, render templates, browse entity/device/area registries
- System tools — System info, config validation, backups, core restart, error log
- Event & calendar tools — List event types, fire events, calendar queries
- State management — Set, delete entity states; handle intents
66 tools across 5 categories, using three HA transport layers: REST API, WebSocket API, and SSH/SFTP.
Prerequisites
- Home Assistant OS (or any HA installation with Supervisor)
- Long-lived access token — Create one in HA → Profile → Security → Long-Lived Access Tokens
- Node.js 20+
- (Optional) SSH app — Required only for file management tools. Install "Advanced SSH & Web Terminal" from the app store.
Quick Start
No installation needed — your MCP client runs the server automatically via npx. Just add the configuration to your client and you're ready to go.
Configuration
The server is configured through environment variables set in your MCP client's configuration file. The client injects these into the server process at launch time — you never need to set system-wide environment variables.
Required Variables
Optional Variables (for file management)
File management tools require SSH access. See Setting Up SSH below.
Getting a Long-Lived Access Token
- Open your Home Assistant UI
- Click your profile icon (bottom-left)
- Scroll to Long-Lived Access Tokens under the Security tab
- Click Create Token, give it a name, and copy the token
MCP Client Setup
Choose the setup for your MCP client below. In each case, add the configuration and the client will automatically download and run the server via npx.
Tip: You can omit the
HA_SSH_*variables if you don't need file management tools. The server will start without SFTP and only fail if you try to use a file tool.
VS Code (GitHub Copilot)
Option A: Install the extension (recommended)
The easiest way — install the Home Assistant MCP Server extension from the VS Code Marketplace. It registers the MCP server automatically and stores your credentials securely.
- Install the extension from the Marketplace (or search "Home Assistant MCP Server" in the Extensions view).
- Set your Home Assistant URL in Settings →
homeAssistantMcp.url. - Run "Home Assistant MCP: Set Access Token" from the Command Palette (
Ctrl+Shift+P). - The MCP server appears in Copilot Chat automatically.
For file management, configure the SSH settings (homeAssistantMcp.ssh.*) and optionally run "Home Assistant MCP: Set SSH Password".
Option B: One-click install via mcp.json
Click the badge at the top of this README, or use the link below. VS Code will prompt you for your Home Assistant URL and access token.
[Install in VS Code]Option C: Manual mcp.json setup
Create .vscode/mcp.json in your workspace (or add to your User Settings for global access):
With SSH (for file management tools):
Claude Desktop
Edit the Claude Desktop config file:
Cursor
Edit ~/.cursor/mcp.json:
Other MCP Clients
Any MCP client that supports stdio servers will work. Use npx as the command with -y @jarahkon/hass-mcp-server@latest as args, and pass HA_URL and HA_TOKEN in the env block.
Setting Up SSH (for file management)
File management tools (ha_upload_file, ha_read_file, ha_list_files, etc.) require SSH access to your Home Assistant instance.
1. Install the SSH app in Home Assistant
- In HA, go to Settings → Apps → App Store
- Install Advanced SSH & Web Terminal
- In the app configuration, set the username to
root(required for SFTP) and enablesftp: true - Configure authentication — either set a password or add your public key to
authorized_keys(recommended) - Start the app and check the logs to confirm it started successfully
2. Generate an SSH key (recommended)
Key-based authentication is more secure than passwords.
This creates ~/.ssh/ha_ed25519 (private key) and ~/.ssh/ha_ed25519.pub (public key).
Add the public key contents to the app configuration in HA:
3. Add SSH variables to your MCP client config
Add these environment variables alongside HA_URL and HA_TOKEN in the env block of your MCP client configuration:
Or if using password authentication:
SSH key path examples
Tool Reference
Dashboards (6 tools)
Files (7 tools) — requires SSH
Automations, Scripts, Scenes & Helpers (17 tools)
Apps & System (18 tools)
Entities & Services (18 tools)
Architecture
The server uses three transport layers to communicate with Home Assistant:
Security Notes
- SFTP path restrictions: Read operations are allowed anywhere under
/config/. Write and delete operations are restricted to safe subdirectories (www/,custom_components/,themes/,blueprints/,scripts/,automations/) and specific files (configuration.yaml,automations.yaml,scripts.yaml,scenes.yaml). Write operations to system directories likedeps/or.storage/are blocked. - Token security: Never commit your
.envfile. The.gitignorealready excludes it. - SSH authentication: Prefer SSH key-based auth (
HA_SSH_KEY_PATH) over passwords. Never commit private keys or passwords to source control.
License
MIT
来源:README.md,提交 1ba71d8
工具
0版本历史
1- v1.0.6最新Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分