Skip to content

Using the MCP server

The MCP server lets an AI assistant work with your Home Assistant directly. You ask it to build or fix a scene in an ordinary conversation, it reads your current setup, and it shows you a preview to confirm before anything is saved. It works with Claude Desktop, Claude Code, and VS Code.

What you need

  • An AI assistant that supports MCP, such as Claude Desktop, Claude Code, or VS Code.
  • uv installed on your computer. This is a small tool that runs the server for you.
  • An admin long-lived access token from Home Assistant. Create one in your profile, under Security → Long-lived access tokens.
  • The web address of your Home Assistant. This can be a local address such as http://homeassistant.local:8123, or a remote address over HTTPS such as a Nabu Casa address or your own domain. Any address you can reach from the computer running your AI assistant will work.

Set it up in Claude Desktop

Add the ambience server to your claude_desktop_config.json file, then restart Claude Desktop:

{
  "mcpServers": {
    "ambience": {
      "command": "uvx",
      "args": ["ambience-mcp@latest"],
      "env": {
        "AMBIENCE_HA_URL": "http://homeassistant.local:8123",
        "AMBIENCE_HA_TOKEN": "<your admin long-lived token>"
      }
    }
  }
}

Replace the address and token with your own.

The @latest matters: it makes uvx check for the newest release every time the server starts, so updates arrive on their own whenever you restart your AI assistant. Without it, the first version you install is the version you keep.

Set it up in Claude Code (and VS Code)

Run the command below, with your own address and token.

On Mac and Linux:

claude mcp add ambience --scope user \
  --env AMBIENCE_HA_URL=http://homeassistant.local:8123 \
  --env AMBIENCE_HA_TOKEN=YOUR_TOKEN \
  -- uvx ambience-mcp@latest

On Windows:

claude mcp add ambience --scope user --env AMBIENCE_HA_URL=http://homeassistant.local:8123 --env AMBIENCE_HA_TOKEN=YOUR_TOKEN -- uvx ambience-mcp@latest

It confirms where it saved the server, with a line like this.

On Linux:

File modified: /home/your_home_dir/.claude.json

On Mac:

File modified: /Users/your_home_dir/.claude.json

On Windows:

File modified: C:\Users\your_home_dir\.claude.json

Check that it is running

Open a new Claude Code conversation — one that is already running will not notice the change. Nothing else is needed for VS Code: the Claude Code extension reads the same settings, so the server is available there too.

Run /mcp to see the server and whether it connected. It works the same in Claude Code in a terminal and in VS Code.

Use it

Ask your assistant to build or fix a scene in plain English. For example:

In the living room, dim the lights when a film starts.

It reads your setup, shows you a preview, and saves the scene once you confirm. The assistant gets everything it needs about Ambience straight from your install, so it always matches your version.

Connect more than one, or pin a version

To connect to several Home Assistant installs, or to install a specific version, see the mcp-server README.

You almost certainly do not want a pinned version: one build works with every Ambience. And if Ambience ever asks you to upgrade ambience-mcp, a pin will keep reinstalling the old build, so the upgrade can never happen — remove the pin first.

Running an Ambience pre-release

If you test Ambience betas, your ambience-mcp has to come from the same channel — uvx installs pre-releases only when you ask it to (@latest does not change that: it means the newest final release), so by default it would keep giving you the last stable ambience-mcp, which may be too old for the beta. Use these args instead:

["--prerelease=allow", "ambience-mcp@latest"]

This is not a pin — you still get the newest build, and upgrades still work. Drop the flag when you go back to a final Ambience release. See Testing an Ambience pre-release.

Your privacy

Ambience removes your private data before it reaches the AI. See Privacy for what is hidden. The "what would happen right now" preview (ambience_dry_run) is hidden the same way. If your Ambience is too old to redact it, the preview carries a visible notice instead of quietly showing the unhidden result — update Ambience to fix that.

Next: Download and paste.