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

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.).

Related MCP server: hass-mcp-plus

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:

1. Generate a dedicated key: ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_hass

2. Add the public key to the Advanced SSH add-on's authorized_keys setting

3. 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.

License

This project is licensed under the MIT License — see LICENSE (© 2026 Logan Boyd).

The vendored base server under mcp_server/vendor/app/ is from voska/hass-mcp, also MIT-licensed (© 2025 Matt Voska) — see mcp_server/vendor/LICENSE and mcp_server/vendor/NOTICE.md.