hass-mcp-extensions

An MCP server that layers additional Home Assistant tools on top of voska/hass-mcp. The base hass-mcp server (MIT, © Matt Voska) is vendored under mcp_server/vendor/ so the repo is self-contained, and extra tools are registered via mcp_server/extensions.py. See mcp_server/vendor/NOTICE.md for provenance and license.

What this adds

Tool	Description
`get_lovelace_dashboard`	Fetch a full Lovelace dashboard config via WebSocket
`get_lovelace_view`	Fetch a single view from a dashboard by title or path
`save_lovelace_dashboard`	Overwrite an entire Lovelace dashboard config
`get_ha_config_item`	Get a stored automation, scene, or script by numeric ID
`get_addon_logs`	Fetch Supervisor add-on logs as plain text
`get_core_log`	Fetch the HA Core log (replaces the removed `/api/error_log` endpoint)
`search_addon_logs`	Grep a Supervisor add-on's logs for a pattern
`read_ha_file`	Read a file from the HA host over SSH
`list_ha_dir`	List a directory on the HA host over SSH
`create_or_update_automation`	Create or overwrite a stored automation via the REST API
`update_stored_scene`	Update a stored scene's entity states
`get_device_info`	Resolve a device's entities, area, and metadata by entity ID or name
`query_recorder_db`	Run a read-only SQL query against the recorder (MariaDB) database
`get_logbook`	Fetch logbook entries from the recorder database
`get_zigbee_events`	Fetch recent Zigbee device events from the recorder database

All base tools from the vendored hass-mcp are also available (get_entity, list_entities, entity_action, call_service_tool, get_history, get_entities_by_area, restart_ha, etc.).

Requirements

Python 3.13+
uv
A running Home Assistant instance with a long-lived access token
For SSH-backed tools (read_ha_file, list_ha_dir): SSH access to the HA host (e.g. via the Advanced SSH & Web Terminal add-on)
For recorder DB tools (query_recorder_db, get_logbook, get_zigbee_events): a connection string to the recorder database (MariaDB/MySQL)

Setup

1. Clone

git clone https://github.com/LoganInTX/home-assistant
cd home-assistant

The base hass-mcp code is vendored in the repo, so no submodule steps are needed.

2. Install dependencies

uv sync

3. Configure credentials

Copy .env.example to .env and fill in your values:

cp .env.example .env

HA_URL=http://homeassistant.local:8123
HA_TOKEN=YOUR_LONG_LIVED_ACCESS_TOKEN

Generate a long-lived access token in Home Assistant under Profile > Long-Lived Access Tokens.

SSH access (optional)

read_ha_file and list_ha_dir shell out to ssh. To use them:

Generate a dedicated key: ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_hass
Add the public key to the Advanced SSH add-on's authorized_keys setting
Set the optional env vars in .env if your host differs from the defaults:

HA_SSH_USER=hassio
HA_SSH_HOST=homeassistant.local
HA_SSH_KEY=~/.ssh/id_ed25519_hass

SSH reads are restricted to /config, /share, /ssl, /addons, /media, and /backup.

Recorder database access (optional)

query_recorder_db, get_logbook, and get_zigbee_events connect directly to the recorder database. Set HA_DB_URL in .env with the recorder's connection string (find it under your recorder integration's db_url):

HA_DB_URL=mysql://homeassistant:YOUR_DB_PASSWORD@core-mariadb/homeassistant?charset=utf8mb4

4. Wire into Claude Code

The repo ships a .mcp.json that registers the server automatically when you open the project in Claude Code. No additional configuration needed.

To use it in a different MCP client, run the server over stdio:

uv run python -m mcp_server

Also included: `add_scenes_view.py`

A standalone script that pushes a Scenes view to the Home Assistant Overview dashboard via WebSocket. Edit the SCENES_VIEW dict at the top of the file, then run:

uv run python add_scenes_view.py

The script connects via WebSocket, finds the existing Scenes view (or appends one), and saves the updated config back to HA. It reads HA_URL and HA_TOKEN from .env.

Adding a new tool

Add an async def decorated with @mcp.tool() to mcp_server/extensions.py. The docstring becomes the tool description shown to MCP clients.

@mcp.tool()
async def my_tool(arg: str) -> str:
    """One-line description shown to the client.

    Args:
        arg: What this argument does.
    """
    ...

Updating the vendored hass-mcp

The base server under mcp_server/vendor/app/ is a vendored copy of voska/hass-mcp (currently v0.4.1). It is no longer a submodule, so newer upstream features must be ported in manually:

# Pull the version you want from upstream, then copy its app/ over the vendored copy
git clone --depth 1 --branch <tag> https://github.com/voska/hass-mcp /tmp/hass-mcp
rsync -a --exclude='__pycache__' /tmp/hass-mcp/app mcp_server/vendor/
uv run python -m mcp_server  # smoke test

Update the version recorded in mcp_server/vendor/NOTICE.md when you do, and re-apply any local modifications to the vendored code.

Security

Never commit .env — it holds your token and DB password, and is gitignored.
SSH access uses a dedicated key with IdentitiesOnly=yes and BatchMode=yes.
File reads over SSH are path-validated against an allowlist before the remote command is issued.