Connect Claude to Home Assistant on Linux in ~10 minutes
A free option is available — the community Claude Desktop build works with a free Claude account. The official Claude Code path needs a paid Claude plan.
Go to claude.ai and create an account.
A free account is enough for the community Claude Desktop path below. Claude Code (the official CLI) requires a paid plan — Pro, Max, Team, or Enterprise.
Anthropic doesn't ship Claude Desktop for Linux, so there are two ways to connect. Pick one:
Anthropic's official CLI. Configured with claude mcp add. Best if you're comfortable in a terminal.
Requires a paid Claude plan.
The desktop app via the community aaddrick/claude-desktop-debian build. Works with a free Claude account.
Unofficial — not maintained by Anthropic.
The officially-supported way to run an MCP server on Linux. Requires a paid Claude plan (Pro, Max, Team, or Enterprise).
Open Terminal and run the official installer:
curl -fsSL https://claude.ai/install.sh | bashSupported on Ubuntu 20.04+, Debian 10+, and Alpine 3.19+. You can also install via apt / dnf / apk or npm install -g @anthropic-ai/claude-code. Verify with claude --version.
Run the installer with the --claude-code flag — it installs uv and registers ha-mcp for the demo environment:
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-codecurl -LsSf https://astral.sh/uv/install.sh | shclaude mcp add home-assistant --scope user \
--env HOMEASSISTANT_URL=https://ha-mcp-demo-server.qc-h.net \
--env HOMEASSISTANT_TOKEN=demo \
-- uvx --python 3.13 ha-mcp@latest--scope user makes the server available in every project (the default scope is the current project only).
Start Claude Code and confirm the server is connected:
claudeOn first launch you'll be prompted to log in (this is where the paid plan is required). Then run /mcp to confirm home-assistant is listed, and ask:
Can you see my Home Assistant?claude mcp list — list configured MCP servers
claude mcp remove home-assistant --scope user — remove this server
Anthropic doesn't ship Claude Desktop for Linux. This path uses the community-maintained aaddrick/claude-desktop-debian build, which repackages the official app for Debian/Ubuntu/Fedora/Arch. It's a well-regarded project, but it's unofficial — if it ever lags an Anthropic Desktop release, this path can break until it catches up.
Follow the instructions for your distro on the aaddrick/claude-desktop-debian project (it ships .deb, .rpm, AUR, Nix, and AppImage builds).
Then sign in to Claude Desktop with your free Claude account.
In Terminal, paste:
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | shThis installs the required tools and configures Claude Desktop for the demo environment.
curl -LsSf https://astral.sh/uv/install.sh | sh{
"mcpServers": {
"Home Assistant": {
"command": "/home/YOUR_USER/.local/bin/uvx",
"args": ["--python", "3.13", "ha-mcp@latest"],
"env": {
"HOMEASSISTANT_URL": "https://ha-mcp-demo-server.qc-h.net",
"HOMEASSISTANT_TOKEN": "demo"
}
}
}
}Replace /home/YOUR_USER/.local/bin/uvx with the output of which uvx. Claude Desktop doesn't inherit your shell's PATH, so a bare uvx will fail with "command not found" on most systems.
4. Save and restart Claude Desktop.
Quit and reopen Claude Desktop so it picks up the new configuration, then ask:
Can you see my Home Assistant?Claude should respond with a list of entities from the demo environment (lights, sensors, switches, etc.).
The demo environment is a real Home Assistant you can experiment with:
Web UI: ha-mcp-demo-server.qc-h.net
Login: mcp / mcp
Note: Resets weekly - your changes won't persist
Try asking Claude:
Ready to use your own Home Assistant? You'll need a long-lived access token:
Re-register the server with your own URL and token:
claude mcp remove home-assistant --scope user
claude mcp add home-assistant --scope user \
--env HOMEASSISTANT_URL=http://homeassistant.local:8123 \
--env HOMEASSISTANT_TOKEN=your_long_lived_token \
-- uvx --python 3.13 ha-mcp@latestOpen the config in your editor (swap nano for your preferred one):
nano ~/.config/Claude/claude_desktop_config.jsonReplace the demo values:
{
"mcpServers": {
"Home Assistant": {
"command": "/home/YOUR_USER/.local/bin/uvx",
"args": ["--python", "3.13", "ha-mcp@latest"],
"env": {
"HOMEASSISTANT_URL": "http://homeassistant.local:8123",
"HOMEASSISTANT_TOKEN": "your_long_lived_token"
}
}
}
}Then quit and reopen Claude Desktop.
If the demo server works but your local Home Assistant doesn't, check the following:
1. Running under WSL?
The Claude Desktop path doesn't work in WSL — Claude Desktop runs on Windows and reads its config from %APPDATA%\Claude\, not the WSL filesystem. Use the Windows guide instead, or use the Claude Code path, which runs fine inside WSL.
2. Firewall rules
If you run ufw or firewalld, make sure outbound connections to your Home Assistant IP and port are allowed. The MCP server runs as a subprocess that needs network access.
3. http:// vs https://
HA in container mode (Docker, K3s) uses HTTP by default. Use http:// unless you configured SSL/TLS or a reverse proxy.
4. Python 3.13 required
ha-mcp requires Python 3.13 (specifically 3.13.x). Older Python can't install the current ha-mcp.
uv python install 3.13
uvx --refresh ha-mcp@latestIf uvx still picks the old Python, make sure "--python", "3.13" is in your config args (as shown above).
See the FAQ & Troubleshooting Guide for more.
We'd love to hear how you're using ha-mcp!
Having issues? See the FAQ & Troubleshooting Guide