mirror of
https://github.com/alexbelgium/hassio-addons.git
synced 2026-09-01 09:43:32 +02:00
13a4548372
Home Assistant's MCP Server integration serves stateless Streamable HTTP at /api/mcp; mcp-proxy defaults to SSE, so the previous registration (SSE at /mcp_server/sse) could never attach. Pass --transport=streamablehttp --stateless and default ha_mcp_url to /api/mcp. Match managed MCP entries by binary basename outside $HOME so a base-image path change still updates them, while user-installed binaries under $HOME remain untouched. Resolve tokensave via command -v like the others. Write Claude config files 0600 (they hold the HA long-lived token in clear text) and scope the build-time chmod +x pass to the shipped script dirs. Docs: dashboard reachability wording, stale /config/data HOME, and the custom-script filename (claude_desktop.sh, per the $slug.sh template). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
142 lines
6.7 KiB
Markdown
142 lines
6.7 KiB
Markdown
# Home assistant add-on: Claude Desktop
|
|
|
|
![Supports aarch64 Architecture][aarch64-shield]
|
|
![Supports amd64 Architecture][amd64-shield]
|
|
![Project Maintenance][maintenance-shield]
|
|
|
|
Run Claude Desktop in a LinuxServer.io Selkies add-on, with Headroom MCP
|
|
context compression, RTK Bash-output acceleration, and code-intelligence
|
|
tooling wired in by default.
|
|
|
|
## Installation
|
|
|
|
1. Add this repository to the Home Assistant add-on store.
|
|
2. Install **Claude Desktop**.
|
|
3. Start the add-on and open the web UI from the sidebar.
|
|
4. Sign in with your Claude account from the Desktop app.
|
|
|
|
Claude Desktop sign-in requires a claude.ai plan that supports the Desktop app.
|
|
API keys are not accepted by the Desktop application. Anthropic's Linux beta
|
|
currently does not include Computer Use or dictation.
|
|
|
|
## Architecture
|
|
|
|
Everything is built around the Claude Desktop app. Claude Code is installed in
|
|
the same image but is not exposed as a standalone service: Claude Desktop's
|
|
cowork and dispatch sessions run it internally, and they pick up the shared
|
|
Claude Code configuration (`~/.claude`), hooks, and MCP servers automatically.
|
|
|
|
- **Claude Desktop** uses Headroom through its MCP tools.
|
|
- **Claude Code sessions inside Desktop** get the same MCP servers via
|
|
`~/.claude.json` and RTK's `PreToolUse` Bash hook via
|
|
`~/.claude/settings.json`.
|
|
- **gnome-keyring** provides the Secret Service backend Electron needs to
|
|
persist sign-in and dispatch permission grants across restarts.
|
|
|
|
## Features
|
|
|
|
- Claude Desktop in single-app Selkies mode with Home Assistant ingress.
|
|
- Official Claude Code stable package powering Desktop cowork/dispatch
|
|
sessions.
|
|
- Persistent `$HOME` at the configured `data_location` (default `/data/data`),
|
|
preserving Desktop and Claude Code state across restarts.
|
|
- Persistent sign-in through a bundled, auto-unlocked gnome-keyring.
|
|
- Optional runtime Claude Desktop updates from Anthropic's apt repository.
|
|
- Optional extra apt and pip package installation (pip installs use `uv` for
|
|
speed).
|
|
- Baked-in `git`, GitHub CLI (`gh`), and `ripgrep`.
|
|
- Custom script support through the repository standard `claude_desktop.sh`.
|
|
- Bundled optimization tools: Headroom (MCP + local proxy), RTK, tokensave,
|
|
and Caveman — each individually switchable.
|
|
- Optional Home Assistant MCP bridge so Claude can query and control Home
|
|
Assistant.
|
|
- Headroom dashboard exposed on mapped port `8787`.
|
|
- Low-power defaults for GPU mapping, Selkies frame rate, and volatile caches.
|
|
|
|
## Options
|
|
|
|
| Option | Default | Description |
|
|
| ------ | ------- | ----------- |
|
|
| `PUID` / `PGID` | `0` / `0` | Numeric user and group applied by the LinuxServer initialization. |
|
|
| `TZ` | | Optional timezone, for example `Europe/Brussels`. |
|
|
| `KEYBOARD` | | Optional Selkies keyboard layout. |
|
|
| `PASSWORD` | | Optional password for direct Selkies ports. |
|
|
| `DRINODE` | | Optional GPU device override for Selkies. |
|
|
| `DNS_server` | `8.8.8.8` | DNS server used by the standard DNS module. |
|
|
| `auto_update` | `true` | Upgrade `claude-desktop` from Anthropic's apt repository at startup. |
|
|
| `install_headroom` | `true` | Register the Headroom MCP server and run the supervised local proxy/dashboard. |
|
|
| `install_rtk` | `true` | Configure RTK's Claude Code `PreToolUse` hook. |
|
|
| `install_tokensave` | `true` | Register the tokensave code-intelligence MCP server for Desktop and Claude Code. |
|
|
| `install_caveman` | `true` | Install the Caveman Claude Code plugin in the persistent Claude home. |
|
|
| `install_github_cli` | `true` | Enable setup checks for the baked-in `git` and `gh` commands. |
|
|
| `github_token` | | Optional GitHub token used to authenticate `gh` and Git operations. |
|
|
| `github_username` | | Optional global Git author name. |
|
|
| `github_email` | | Optional global Git author email. |
|
|
| `enable_ha_mcp` | `false` | Register Home Assistant's MCP server in Claude (requires `ha_mcp_token`). |
|
|
| `ha_mcp_url` | `http://homeassistant:8123/mcp_server/sse` | SSE endpoint of Home Assistant's MCP Server integration. |
|
|
| `ha_mcp_token` | | Home Assistant long-lived access token used by the MCP bridge. |
|
|
| `additional_apps` | | Comma-separated Debian apt packages to install at startup. |
|
|
| `additional_pip` | | Comma-separated pip packages installed at startup (via `uv`). |
|
|
| `data_location` | `/data/data` | Persistent home directory for Claude and tooling. |
|
|
| `env_vars` | `[]` | Additional environment variables exported inside the container. |
|
|
|
|
## Headroom behavior
|
|
|
|
When `install_headroom` is enabled, the add-on registers `headroom mcp serve`
|
|
in Claude Desktop and Claude Code, and starts a supervised local Headroom
|
|
backend. Claude can use `headroom_compress`, `headroom_retrieve`, and
|
|
`headroom_stats` through MCP.
|
|
|
|
Claude Desktop overrides `ANTHROPIC_BASE_URL`, so it is deliberately launched
|
|
without proxy injection; the MCP integration is the supported path.
|
|
|
|
The Headroom dashboard is available at:
|
|
|
|
```text
|
|
http://<home-assistant-host>:8787/dashboard
|
|
```
|
|
|
|
through the default `8787/tcp` port mapping. The dashboard is unauthenticated
|
|
and is reachable wherever Home Assistant publishes that port, so treat it as
|
|
sensitive: do not expose it directly to the public internet, and unmap the port
|
|
in the add-on **Network** section if you do not want it reachable at all.
|
|
|
|
## Home Assistant MCP bridge
|
|
|
|
To let Claude query and control Home Assistant:
|
|
|
|
1. In Home Assistant, add the **Model Context Protocol Server** integration
|
|
(Settings → Devices & services → Add integration).
|
|
2. Create a long-lived access token (your profile → Security).
|
|
3. Set `enable_ha_mcp: true` and paste the token into `ha_mcp_token` in the
|
|
add-on configuration, then restart the add-on.
|
|
|
|
The add-on bridges Claude to the integration's stateless Streamable HTTP
|
|
endpoint (`/api/mcp`) with `mcp-proxy`. Override `ha_mcp_url` only if your Home
|
|
Assistant instance is not reachable as `homeassistant:8123` from add-ons.
|
|
|
|
## Custom scripts
|
|
|
|
The add-on includes the repository standard custom-script executor. On first
|
|
start, it seeds `claude_desktop.sh` in the add-on config directory. Commands in
|
|
that script run during startup, allowing local customization without rebuilding
|
|
the image.
|
|
|
|
## Data and cache locations
|
|
|
|
Persistent state is stored in the configured `data_location` (default
|
|
`/data/data`):
|
|
|
|
- Claude Desktop sign-in: `~/.config/Claude` (token encrypted via
|
|
gnome-keyring; keyring DB in `~/.local/share/keyrings`)
|
|
- Claude Code settings, hooks, sessions, and plugins: `~/.claude`
|
|
- Headroom, RTK, and tokensave user state: their standard paths below the
|
|
shared home
|
|
|
|
Volatile cache data is redirected to `/tmp/cache` through `$XDG_CACHE_HOME` and
|
|
`$HOME/.cache`.
|
|
|
|
[aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg
|
|
[amd64-shield]: https://img.shields.io/badge/amd64-yes-green.svg
|
|
[maintenance-shield]: https://img.shields.io/maintenance/yes/2026.svg
|