dirigera-mcp

An MCP server that lets an MCP client (Claude Code) control IKEA TRÅDFRI smart plugs ("strömbrytare") paired to a DIRIGERA hub.

It talks to the hub over its local REST API (HTTPS on port 8443, bearer-token auth) using the dirigera library. Nothing goes through IKEA's cloud.

Transports	stdio, or streamable-http for sharing one hub connection across devcontainers
SDK	official Python MCP SDK (mcp 2.0.0, MCPServer)
Hub client	dirigera 1.2.7
Server	src/dirigera_mcp/server.py
Pairing helper	scripts/get_token.py

---

Setup

The hub issues a long-lived access token only after someone physically presses its action button. That token then has to reach the container, and it does so from your host environment via devcontainer remoteEnv — it is never committed, never written to a file in this repo, and never logged.

Do these three steps in order.

1. Generate the token

In a terminal inside the container:

python scripts/get_token.py

The script prints the hub address, then tells you to press the action button (the small recessed button on the underside of the hub). Press it, come back, hit ENTER, and the token is printed to stdout. You have about 60 seconds.

If you are driving this non-interactively, use the countdown mode instead — no ENTER needed:

python scripts/get_token.py --wait 30

The address comes from $DIRIGERA_HUB_IP; pass --ip <address> if it is not set yet.

The token is printed once and is not saved anywhere. Copy it now. If you lose it, just run the script again — pairing again is harmless and does not invalidate other tokens.

Prefer running this in your own VS Code terminal rather than having Claude run it, so the credential does not end up in a chat transcript.

2. Put it in your HOST user environment

Not in the container, and not in a .env file — the whole point of the setup is that the credential lives on the host and is injected at runtime.

On Windows, in a PowerShell window on the host:

[Environment]::SetEnvironmentVariable("DIRIGERA_TOKEN", "<paste-the-token>", "User")
[Environment]::SetEnvironmentVariable("DIRIGERA_HUB_IP", "<your-hub-ip>", "User")

On macOS/Linux hosts, put the two export lines in your shell profile (~/.zshrc, ~/.bashrc) and make sure VS Code is launched from a shell that has sourced it.

DIRIGERA_HUB_IP is required. It has no default in the source: a baked-in fallback would be one specific person's LAN address. It is also what the sandbox firewall opens its single exception for, so the same value drives both.

3. Restart VS Code and reopen the container

First confirm the values really persisted. In PowerShell — this reads the stored User-scope value directly, so it works even in the window that just set it:

[Environment]::GetEnvironmentVariable("DIRIGERA_TOKEN", "User").Length   # expect ~400, not 0
[Environment]::GetEnvironmentVariable("DIRIGERA_HUB_IP", "User")         # expect your hub address

Then restart VS Code. A Windows process inherits its environment at launch and never sees User variables created afterwards, so a window reload — and even a container rebuild — is not enough: the value comes from the running VS Code process, not from the container.

1. Quit every VS Code instance, including windows holding unrelated projects. VS Code runs one shared main process on Windows and new windows inherit its environment, so a single surviving window is enough to keep the stale environment alive. code . from a fresh shell does not help either — it just signals the existing instance.
2. Confirm nothing survived: Get-Process code -ErrorAction SilentlyContinue should print nothing. If processes linger without visible windows, ... | Stop-Process (save your work first).
3. Start VS Code again, open this folder, and Reopen in Container.

No rebuild is needed. Closing the last window stops the container (shutdownAction defaults to stopContainer), and the next attach re-reads remoteEnv.

Verify inside the container, in a bash terminal (this is bash syntax; it silently prints empty values if you run it in PowerShell):

echo "hub=$DIRIGERA_HUB_IP token_length=${#DIRIGERA_TOKEN}"

A non-zero token_length means the token arrived. Then restart Claude Code so it picks up the dirigera server from .mcp.json, and ask it to list your outlets.

Troubleshooting

The variables exist in the container but are empty (env | grep DIRIGERA shows both names with no values). remoteEnv is working; ${localEnv:...} resolved to nothing. That means VS Code was started before the host variables were created — quit it fully and relaunch, as above.

Still empty after a full restart. Check whether VS Code is reading the Windows environment at all: if /home/vscode/.gitconfig-host exists and is non-empty, ${localEnv:USERPROFILE} resolved, so the mechanism works and only the DIRIGERA values are missing. If that file is missing, VS Code is resolving localEnv somewhere else — typically because the window was opened through Remote-WSL, where Windows User variables are not visible unless forwarded via WSLENV. Set the two variables inside WSL instead, or open the folder as a Windows path.

The tools work but the plug does not switch. Check is_reachable in the result. The hub accepts writes for offline devices, so the server flags this with a warning field rather than reporting a state it cannot confirm.

---

MCP tools

Tool	Arguments	Returns
list_outlets	—	every outlet: id, name, room, is_on, is_reachable
get_outlet	outlet_id	current state of one outlet, read fresh from the hub
set_outlet	outlet_id, on (bool)	new state, plus previous_is_on
toggle_outlet	outlet_id	new state, plus previous_is_on
power_cycle	outlet_id, off_seconds (0.5–300, default 5)	state after power is restored

power_cycle switches the outlet off, waits, and switches it back on — for rebooting hardware such as a development board. Power is restored on every path out of the wait, and the call refuses outright on an unreachable outlet rather than risk cutting power it cannot restore. The call blocks for off_seconds, so keep it well inside the client's tool-call timeout.

set_outlet and toggle_outlet re-read the outlet from the hub after writing, so the state they report is the hub's, not an optimistic guess. If the hub reports the plug as unreachable, the result carries a warning field — the hub accepts writes for offline devices, so a successful call is not by itself proof that the plug switched.

Every failure comes back as a plain sentence, not a stack trace:

Situation	What the client sees
DIRIGERA_TOKEN empty	"DIRIGERA_TOKEN is not set in this container's environment…" + how to fix
Token wrong/expired (401/403)	"The hub rejected the token…" + how to regenerate
Hub off or wrong IP	"Cannot reach the DIRIGERA hub at <ip>:8443…"
Unknown outlet id	"Device id not found. Call list_outlets to get the ids…"
Id belongs to a lamp, not a plug	"Device is not an outlet. Call list_outlets…"

---

Registration

The server is registered in the repo's .mcp.json alongside the other project servers:

"dirigera": {
    "type": "stdio",
    "command": "/workspaces/ikea-mcp/.venv/bin/python",
    "args": ["/workspaces/ikea-mcp/src/dirigera_mcp/server.py"],
    "env": {
        "DIRIGERA_HUB_IP": "${DIRIGERA_HUB_IP:-}",
        "DIRIGERA_TOKEN": "${DIRIGERA_TOKEN:-}"
    }
}

Absolute paths, because the client chooses the working directory. The :- defaults let the server start even with the variables unset, so an unconfigured setup produces a helpful tool error instead of a server that fails to launch.

The server is a single module run directly by the venv interpreter — the project is not installed as a package, so there is no build step and uv sync is all that is needed.

---

Sharing one server with other devcontainers

An MCP stdio server is spawned as a child process by its client, so Claude Code running inside devcontainer X always starts the server inside X. Installing it on the host does nothing for a containerised client. To use one hub connection from several projects, run the server over HTTP.

The payoff: the hub token and the firewall's LAN exception exist in exactly one place. Project containers get neither — they only reach host.docker.internal.

Run it on the host

docker compose from deploy/, with both secrets in the shell's environment:

$env:DIRIGERA_MCP_KEY = python -c "import secrets; print(secrets.token_urlsafe(32))"
[Environment]::SetEnvironmentVariable("DIRIGERA_MCP_KEY", $env:DIRIGERA_MCP_KEY, "User")
cd deploy
docker compose up -d --build

DIRIGERA_MCP_KEY is the shared secret between the server and every client. Without it the server refuses to start over HTTP — an unauthenticated endpoint here can cut power to whatever is plugged in.

To run the published image instead of building locally — no clone needed on the host:

docker run -d --name dirigera-mcp --restart unless-stopped `
  -p 127.0.0.1:8765:8765 `
  -e DIRIGERA_HUB_IP -e DIRIGERA_TOKEN -e DIRIGERA_MCP_KEY `
  ghcr.io/david-s-svedberg/ikea-mcp:latest

.github/workflows/publish-image.yml builds and publishes that image on every push to main, using the workflow's built-in GITHUB_TOKEN. The image holds no credentials; both secrets arrive as runtime environment.

Point a project at it

In that project's .mcp.json:

"dirigera": {
    "type": "http",
    "url": "http://host.docker.internal:8765/mcp",
    "headers": { "Authorization": "Bearer ${DIRIGERA_MCP_KEY}" }
}

The project's devcontainer needs DIRIGERA_MCP_KEY in remoteEnv (same host-variable flow as the token above) and must allow egress to host.docker.internal. Under the firewall pattern in .devcontainer/init-firewall.sh that is already covered by the 192.168.65.0/24 carve-out for Docker Desktop's internal services. No LAN exception is needed.

Security properties

Check	Behaviour
Missing or wrong Authorization	401, constant-time comparison so the secret does not leak byte by byte
Forged Host header	421, DNS-rebinding protection with an explicit allow-list
Published port	host loopback only, so the endpoint is not on the LAN
Image contents	no credentials; both secrets arrive as runtime environment

Verified locally over HTTP: 401 without and with a wrong secret, 421 on a forged Host header, and a working session against the real hub with the correct one.

Loopback publishing is enough — verified on Docker Desktop for Windows. With the port published as 127.0.0.1:8765:8765, a devcontainer resolves host.docker.internal to the Docker Desktop gateway (192.168.65.254), which proxies through to the host's loopback and reaches the server. The port stays off the LAN while remaining reachable from containers.

If a different Docker setup cannot do that, publish on all interfaces ("8765:8765") and block the port from outside in the host firewall, or put the server and the project container on a shared user-defined Docker network and address it by container name.

Sandbox notes

This devcontainer is hardened (see .devcontainer/init-firewall.sh): egress to RFC1918 space is rejected, with exactly one exception for $DIRIGERA_HUB_IP:8443.

No LAN address is committed anywhere in this repo. The firewall script takes the hub address as an argument, which devcontainer.json fills from remoteEnv, and the Python side reads the same variable. Renumbering the hub therefore means changing one value in your host environment. If DIRIGERA_HUB_IP is unset the script falls back to RFC 5737 documentation space, so it fails closed: the exception points at an address nothing answers on, and the real hub stays blocked.

Interactive sudo is disabled. System packages belong in .devcontainer/Dockerfile, followed by a container rebuild.

The hub serves a self-signed certificate, so the dirigera library disables TLS verification. That is the library's own behaviour and acceptable here: the connection is to a single pinned LAN IP that the firewall restricts to one port.

Development

uv sync                       # install locked deps into .venv
ruff check src scripts        # lint