deConz MCP Server

An MCP (Model Context Protocol) server that exposes the deCONZ REST API to AI assistants. Control Zigbee lights, sensors, groups, scenes, rules, and schedules through natural language.

Supports stdio, SSE, and Streamable HTTP transports. HTTP transports are protected by a configurable bearer token.

Requirements

• Python ≥ 3.10
• uv (recommended) or pip
• A running deCONZ / Phoscon gateway with a ConBee or RaspBee adapter
• A valid deCONZ REST API key (see Obtaining an API key)

Installation

# Clone the repository
git clone https://github.com/marcinn2/deconz-mcp.git
cd deconz-mcp

# Install with uv (creates an isolated virtual environment)
uv sync

# Or install with pip into your environment
pip install -e .

Obtaining an API key

1. Open the Phoscon App in your browser (usually `http:///pwa`).

2. Go to Menu → Settings → Gateway → Advanced.

3. Click Authenticate app — this opens the network for 60 seconds.

4. Within those 60 seconds, run:

curl -s -X POST http:///api \
  -H "Content-Type: application/json" \
  -d '{"devicetype": "deconz-mcp"}'

The response contains your API key:

[{"success": {"username": "YOUR-API-KEY-HERE"}}]

Store it as `DECONZ_API_KEY`.

Quick start

stdio (Claude Desktop)

DECONZ_HOST=192.168.1.10 DECONZ_API_KEY=abc123def deconz-mcp

Streamable HTTP with bearer auth

DECONZ_HOST=192.168.1.10 \
DECONZ_API_KEY=abc123def \
MCP_AUTH_TOKEN=my-mcp-secret \
deconz-mcp --transport streamable-http --host 0.0.0.0 --port 8080

Combined SSE + Streamable HTTP

DECONZ_HOST=192.168.1.10 \
DECONZ_API_KEY=abc123def \
MCP_AUTH_TOKEN=my-mcp-secret \
deconz-mcp --transport server --host 0.0.0.0 --port 8080

Environment variables

\* Not required when using stdio and calling `configure_deconz` at runtime.

† Strongly recommended for HTTP transports exposed beyond localhost.

‡ Defaults to enabled only when `DECONZ_HOST` / `DECONZ_API_KEY` are absent. Once the gateway

is configured from the environment, the tool is withheld so that a client cannot repoint this

server at another host.

CLI reference

usage: deconz-mcp [--transport {stdio,sse,streamable-http,server}]
                  [--host HOST] [--port PORT]
                  [--log-level {DEBUG,INFO,WARNING,ERROR}]
                  [--auth-token TOKEN] [--base-url URL]

Transport modes

Authentication

deCONZ API key

The deCONZ REST API key is a gateway credential that travels as part of the URL path (`/api//...`). It is configured server-side via `DECONZ_API_KEY` and is never exposed to MCP clients: request URLs are kept out of tool errors, and the HTTP client's request logging is silenced because it would otherwise write the key to stderr on every call.

Resource IDs supplied by a client (light, group, scene, sensor, rule, schedule, and Touchlink IDs) are validated before they are placed in a request path, so a crafted ID cannot escape its resource and reach, for example, the gateway's configuration or its list of API keys.

MCP bearer token

The `MCP_AUTH_TOKEN` / `--auth-token` option protects the MCP server itself. Every HTTP request from an MCP client must include:

Authorization: Bearer

The token is verified with a constant-time comparison to prevent timing attacks. When running over localhost only (default bind `127.0.0.1`), bearer auth is optional but recommended.

Tools

Connection / configuration

Lights

Groups

Scenes

Sensors

Rules (automations)

Schedules

Touchlink

Resources

Resources are read-only, cacheable snapshots that MCP clients can fetch without issuing tool calls.

Prompts

Prompts are pre-built conversation starters that guide the AI through common workflows.

Claude Desktop configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

{
  "mcpServers": {
    "deconz": {
      "command": "deconz-mcp",
      "env": {
        "DECONZ_HOST": "192.168.1.10",
        "DECONZ_API_KEY": "your-api-key-here"
      }
    }
  }
}

Or if installed in a virtual environment:

{
  "mcpServers": {
    "deconz": {
      "command": "/path/to/deconz-mcp/.venv/bin/deconz-mcp",
      "env": {
        "DECONZ_HOST": "192.168.1.10",
        "DECONZ_API_KEY": "your-api-key-here"
      }
    }
  }
}

HTTP client configuration

For Streamable HTTP transport:

{
  "mcpServers": {
    "deconz": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer my-mcp-secret"
      }
    }
  }
}

For legacy SSE transport:

{
  "mcpServers": {
    "deconz": {
      "url": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer my-mcp-secret"
      }
    }
  }
}

Docker

A multi-platform image (linux/amd64 + linux/arm64) is published to GitHub Container Registry by the release workflow whenever a version tag is pushed:

ghcr.io/marcinn2/deconz-mcp:latest
ghcr.io/marcinn2/deconz-mcp:0.2
ghcr.io/marcinn2/deconz-mcp:0.2.1

A multi-stage `Dockerfile` is also included if you prefer to build locally. The builder stage uses the official `uv` image to install dependencies and compile the package as a wheel; the runtime stage is `python:3.14-slim` and runs as the unprivileged user `app` (uid 1000).

Pull

docker pull ghcr.io/marcinn2/deconz-mcp:latest

Build locally

# Single-platform (current machine)
docker build -t deconz-mcp:latest .

# Multi-platform push (requires a buildx builder with multi-platform support).
# Releases do this automatically; this is for pushing to another registry by hand.
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag registry.mne.pl/deconz-mcp:latest \
  --tag registry.mne.pl/deconz-mcp:0.2.1 \
  --push .

Run — HTTP server (SSE + Streamable HTTP)

docker run -p 8000:8000 \
  -e DECONZ_HOST=192.168.1.10 \
  -e DECONZ_API_KEY=abc123def \
  -e MCP_AUTH_TOKEN=my-mcp-secret \
  ghcr.io/marcinn2/deconz-mcp:latest

Run — stdio

docker run -i \
  -e DECONZ_HOST=192.168.1.10 \
  -e DECONZ_API_KEY=abc123def \
  ghcr.io/marcinn2/deconz-mcp:latest --transport stdio

Docker Compose

A ready-to-use Compose file is in `docs/docker-compose.yml`. It defines two services:

# Copy and edit the environment file
cp .env.example .env   # set DECONZ_HOST, DECONZ_API_KEY, MCP_AUTH_TOKEN

# Start the HTTP server (--env-file is required: the compose file lives in docs/,
# so a repository-root .env is not picked up automatically)
docker compose --env-file .env -f docs/docker-compose.yml up

# Run a one-shot stdio session
docker compose --env-file .env -f docs/docker-compose.yml --profile stdio run --rm deconz-mcp-stdio

Use the stdio service in Claude Desktop:

{
  "mcpServers": {
    "deconz": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/docs/docker-compose.yml",
               "--profile", "stdio", "run", "--rm", "deconz-mcp-stdio"],
      "env": {
        "DECONZ_HOST": "192.168.1.10",
        "DECONZ_API_KEY": "your-api-key-here"
      }
    }
  }
}

Kubernetes

The manifest at `docs/k8s-deployment.yaml` contains all resources needed to run the server in a cluster:

Deploy

# 1. Encode your secrets
echo -n 'your-api-key'   | base64   # → paste into Secret.DECONZ_API_KEY
echo -n 'your-mcp-token' | base64   # → paste into Secret.MCP_AUTH_TOKEN

# 2. Edit the ConfigMap (DECONZ_HOST, MCP_BASE_URL) in docs/k8s-deployment.yaml

# 3. Apply
kubectl apply -f docs/k8s-deployment.yaml

# 4. Verify
kubectl -n deconz-mcp get pods
kubectl -n deconz-mcp logs -f deploy/deconz-mcp

Health check

kubectl -n deconz-mcp port-forward svc/deconz-mcp 8000:80
curl http://localhost:8000/health
# {"status": "ok", "deconz_configured": true}

The `Deployment` configures both a liveness probe and a readiness probe against `/health`, so Kubernetes automatically restarts the pod if the server becomes unresponsive.

Ingress (optional)

Uncomment the `Ingress` section at the bottom of `docs/k8s-deployment.yaml` and set your hostname. Do not add a `rewrite-target` annotation: the endpoints live at `/mcp`, `/sse` and `/messages/` and must reach the pod with their paths intact. TLS termination happens at the ingress controller; the pod always speaks plain HTTP internally.

Health check

HTTP transports expose a liveness probe:

curl http://localhost:8080/health
# {"status": "ok", "deconz_configured": true}

Project structure

deConz-mcp/
├── Dockerfile                      # Multi-stage image build (runs as uid 1000)
├── pyproject.toml                  # Package metadata and dependencies
├── uv.lock                         # Locked dependency versions (committed)
├── .env.example                    # Template for docker compose
├── README.md
├── docs/
│   ├── docker-compose.yml          # Compose services (HTTP + stdio)
│   └── k8s-deployment.yaml         # Kubernetes: Namespace, Secret, ConfigMap,
│                                   #   Deployment, Service, Ingress (template)
├── tests/
│   └── test_smoke.py               # Client, credential-handling and MCP surface tests
└── src/
    └── deconz_mcp/
        ├── __init__.py
        ├── __main__.py             # CLI entrypoint and transport wiring
        ├── client.py               # Async deCONZ REST API HTTP client
        └── server.py               # FastMCP server: tools, resources, prompts

deCONZ API overview

The server covers these API categories:

For the full API reference, see the deCONZ REST API documentation.

Data & Privacy

> Preliminary assessment only — not legal advice. See full notes below.

Personal home use

When this server runs in a private household and is accessed only by the residents, processing of smart-home device data is likely covered by the household exemption (GDPR Recital 18). In that scenario the GDPR does not apply and no additional compliance steps are required.

Commercial or shared deployments

Deploying this server in offices, rental properties, hotels, co-working spaces, or any environment where you process data on behalf of other people takes you outside the household exemption. In those cases:

• Presence and motion sensor data constitutes personal behavioral data (Art. 4(1) GDPR). Establish a documented lawful basis (Art. 6) before processing it.
• Conduct a Data Protection Impact Assessment (Art. 35) if the deployment involves systematic monitoring of occupants on a large scale.
• Provide a privacy notice to data subjects describing what is collected, for how long, and under what legal basis.

Security recommendations

What this software does NOT do

• No data is sent to third parties, analytics services, or cloud providers.
• No telemetry, tracking pixels, or consent libraries are present in this codebase.
• All communication stays between the MCP client, this server, and the local deCONZ gateway.

Legal notice

This GDPR assessment was generated as a preliminary, exploratory evaluation. It does not constitute legal advice and does not replace a legal audit. For binding guidance, consult a qualified data protection lawyer in your jurisdiction.

Releasing

Releases are cut by pushing a version tag. `.github/workflows/release.yml` then:

1. Checks that the tag matches the `version` in `pyproject.toml` and fails early if it does not.

2. Runs the full CI workflow (lint, format, type-check, tests on Python 3.10–3.12).

3. Builds the image for linux/amd64 and linux/arm64, with an SBOM and build provenance, and pushes it to `ghcr.io/marcinn2/deconz-mcp`.

4. Creates the GitHub release with generated notes, the image digest, and the built wheel and sdist attached.

# bump version = "0.3.0" in pyproject.toml first, then:
git tag -a v0.3.0 -m "v0.3.0"
git push origin v0.3.0

A tag containing a hyphen, such as `v0.3.0-rc.1`, is published as a pre-release and does not move the `latest` image tag.

Image tags produced for `v0.3.0`: `0.3.0`, `0.3`, and `latest`.

No secrets need to be configured: the workflow authenticates to GHCR with the built-in `GITHUB_TOKEN`. After the first release, set the package visibility under Packages → deconz-mcp → Package settings if the image should be pullable anonymously.

License

Apache 2.0 — see LICENSE.

Disclaimer

This software is not affiliated with or endorsed by Dresden Elektronik. Use at your own risk. It does not come with any warranty of any kind. There is no liability for the developer. This software is a personal project that I maintain in my free time.

Refer to the licence for more information.