Home Assistant MCP Server
io.github.jarahkonPublished by GitHub account jarahkonv1.0.6Updated Oct 24, 2026
MCP server for full Home Assistant control — dashboards, files, automations, add-ons, and more
Overview
Local MCP server that gives an assistant broad control over a Home Assistant instance: dashboards, automations, files, apps, entities and services.
- What you can do
- List, create, update, delete and deploy Lovelace dashboards, including full config JSON
- Upload, read, list, create and delete files on the HA instance over SFTP
- Manage automations, scripts, scenes and input helpers with full create/read/update/delete
- Install, start, stop, restart, uninstall and configure apps, plus system info, config validation, backups, core restart and error log
- Query entity states, call services, render templates, browse entity/device/area registries, read history and logbook, fire events, set states and query calendars
- When to use it
- Useful when you want an assistant to build or edit Home Assistant dashboards, write automations and scripts, inspect entity states and history, or manage add-ons and backups without clicking through the HA interface yourself.
- Requirements
- Runs locally via npx, so Node.js 20+ is needed. Requires a Home Assistant installation with Supervisor, the HA_URL base URL and a long-lived access token in HA_TOKEN. File tools additionally need the Advanced SSH & Web Terminal app with SFTP enabled and HA_SSH_HOST, HA_SSH_USER (root) plus either HA_SSH_KEY_PATH or HA_SSH_PASSWORD.
Installation
In SourceWeft
- Open Home Assistant MCP Server in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
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
Source: README.md at commit 1ba71d8
Tools
0Version history
1- v1.0.6LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts