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

概覽

AI 產生的概覽

本機 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 其中之一。
安裝前請注意
權杖與 SSH 憑證可對家庭自動化系統進行廣泛控制。許多工具會寫入、重新啟動或刪除:儀表板、自動化、指令碼、場景、輔助元素、檔案、應用程式、實體狀態、核心設定及核心重新啟動。SSH 使用 root 帳號,SFTP 寫入雖限於特定目錄,仍會改動使用中的設定檔。請勿將 HA_TOKEN、HA_SSH_PASSWORD 和私鑰提交到版本控制,並優先使用金鑰認證。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Home Assistant MCP Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

[hass-mcp-server]

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

VariableDescriptionExample
HA_URLHome Assistant base URLhttp://homeassistant.local:8123
HA_TOKENLong-lived access token(from HA Profile → Security)

Optional Variables (for file management)

File management tools require SSH access. See Setting Up SSH below.

VariableDescriptionExample
HA_SSH_HOSTSSH hostnamehomeassistant.local
HA_SSH_PORTSSH port (default: 22)22
HA_SSH_USERSSH username (must be root)root
HA_SSH_KEY_PATHPath to SSH private keySee examples per OS
HA_SSH_PASSWORDSSH password (alternative to key)(your password)

Getting a Long-Lived Access Token

  1. Open your Home Assistant UI
  2. Click your profile icon (bottom-left)
  3. Scroll to Long-Lived Access Tokens under the Security tab
  4. 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.

  1. Install the extension from the Marketplace (or search "Home Assistant MCP Server" in the Extensions view).
  2. Set your Home Assistant URL in Settings → homeAssistantMcp.url.
  3. Run "Home Assistant MCP: Set Access Token" from the Command Palette (Ctrl+Shift+P).
  4. 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):

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}"      }    }  }}

With SSH (for file management tools):

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}",        "HA_SSH_HOST": "homeassistant.local",        "HA_SSH_USER": "root",        "HA_SSH_KEY_PATH": "/home/you/.ssh/ha_ed25519"      }    }  }}

Claude Desktop

Edit the Claude Desktop config file:

OSConfig file path
Windows%APPDATA%\Claude\claude_desktop_config.json
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Linux~/.config/Claude/claude_desktop_config.json
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

Edit ~/.cursor/mcp.json:

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"      }    }  }}

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

  1. In HA, go to Settings → Apps → App Store
  2. Install Advanced SSH & Web Terminal
  3. In the app configuration, set the username to root (required for SFTP) and enable sftp: true
  4. Configure authentication — either set a password or add your public key to authorized_keys (recommended)
  5. 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.

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

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:

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

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:

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

Or if using password authentication:

json
"HA_SSH_HOST": "homeassistant.local","HA_SSH_USER": "root","HA_SSH_PASSWORD": "your_ssh_password_here"
SSH key path examples
OSExample HA_SSH_KEY_PATH
WindowsC:/Users/you/.ssh/ha_ed25519
macOS/Users/you/.ssh/ha_ed25519
Linux/home/you/.ssh/ha_ed25519

Tool Reference

Dashboards (6 tools)

ToolDescription
ha_list_dashboardsList all Lovelace dashboards
ha_create_dashboardCreate a new dashboard with url_path, title, icon
ha_update_dashboardUpdate dashboard properties (title, icon, sidebar visibility)
ha_delete_dashboardDelete a dashboard by ID
ha_get_dashboard_configGet the full Lovelace config JSON for a dashboard
ha_save_dashboard_configDeploy a complete Lovelace config to a dashboard

Files (7 tools) — requires SSH

ToolDescription
ha_list_filesList files in a directory on HA (relative to /config/)
ha_read_fileRead file contents from HA
ha_upload_fileUpload a local file to HA via SFTP
ha_upload_file_contentWrite string content directly to a file on HA
ha_delete_fileDelete a file on HA (restricted to safe directories)
ha_mkdirCreate a directory on HA
ha_file_existsCheck if a file or directory exists on HA

Automations, Scripts, Scenes & Helpers (17 tools)

ToolDescription
ha_list_automationsList all automations
ha_get_automationGet a specific automation's config by ID
ha_create_automationCreate a new automation
ha_update_automationUpdate an existing automation
ha_delete_automationDelete an automation
ha_list_scriptsList all scripts
ha_create_scriptCreate a new script
ha_update_scriptUpdate an existing script
ha_delete_scriptDelete a script
ha_list_scenesList all scenes
ha_create_sceneCreate a new scene
ha_update_sceneUpdate an existing scene
ha_delete_sceneDelete a scene
ha_list_helpersList all input helpers (booleans, numbers, etc.)
ha_create_helperCreate an input helper of any type
ha_update_helperUpdate an existing helper
ha_delete_helperDelete a helper

Apps & System (18 tools)

ToolDescription
ha_list_addonsList all installed apps with status
ha_addon_infoGet detailed info about a specific app
ha_install_addonInstall an app by slug
ha_start_addonStart an app
ha_stop_addonStop an app
ha_restart_addonRestart an app
ha_uninstall_addonUninstall an app
ha_addon_optionsGet or set app configuration options
ha_system_infoGet system info (core, OS, supervisor, host)
ha_check_configValidate HA configuration before reload
ha_create_backupCreate a full or partial backup
ha_list_backupsList all backups
ha_restart_coreRestart Home Assistant core
ha_check_apiCheck if the HA API is accessible and responding
ha_get_configGet HA configuration (location, units, version, components)
ha_update_core_configUpdate core configuration (internal/external URL, location, units)
ha_get_componentsList all loaded HA integrations/components
ha_get_error_logGet the Home Assistant error log contents

Entities & Services (18 tools)

ToolDescription
ha_get_statesGet all entity states (optionally filtered by domain)
ha_get_entityGet full state and attributes of a specific entity
ha_call_serviceCall any HA service (turn_on, turn_off, notify, etc.)
ha_list_servicesList available services by domain
ha_render_templateRender a Jinja2 template
ha_list_entity_registryList entities from the entity registry
ha_list_devicesList all devices
ha_list_areasList all areas (rooms)
ha_create_areaCreate a new area
ha_get_historyGet state history for an entity over a time period
ha_get_logbookGet logbook entries (activity log), optionally filtered by entity
ha_get_eventsList all available event types
ha_fire_eventFire a custom event to trigger automations
ha_set_stateSet or create an entity state (virtual sensors, overrides)
ha_delete_stateDelete an entity state
ha_get_calendarsList all calendar entities
ha_get_calendar_eventsGet events from a specific calendar
ha_handle_intentHandle a conversation/voice intent

Architecture

The server uses three transport layers to communicate with Home Assistant:

LayerUsed ForLibrary
REST API (/api/...)Service calls, states, history, templates, Supervisor proxy, automation/script/scene CRUDBuilt-in fetch
WebSocket API (/api/websocket)Dashboard CRUD, helper CRUD, entity registryws
SSH/SFTPFile upload/download/list/delete on HA filesystemssh2-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

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 like deps/ or .storage/ are blocked.
  • Token security: Never commit your .env file. The .gitignore already 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
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v1.0.6最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分