Mcp Server For Deconz Server

deConz MCP サーバー

AI アシスタントに deCONZ REST API を公開する MCP（Model Context Protocol） サーバーです。自然言語を使って、Zigbee のライト、センサー、グループ、シーン、ルール、スケジュールを操作できます。

stdio、SSE、Streamable HTTP のトランスポートに対応しています。HTTP トランスポートは、設定可能なベアラートークンで保護されています。

---

要件

• Python ≥ 3.10
• uv（推奨）または pip
• ConBee または RaspBee アダプターを搭載した、稼働中の deCONZ / Phoscon ゲートウェイ
• 有効な deCONZ REST API キー（API キーの取得を参照）

---

インストール

# 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 .

---

API キーの取得

1. ブラウザーで Phoscon App を開きます（通常は http://<gateway-ip>/pwa）。
2. Menu → Settings → Gateway → Advanced に移動します。
3. Authenticate app をクリックします。これにより、ネットワークが 60 秒間開放されます。
4. 60 秒以内に、次のコマンドを実行します。

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

応答に API キーが含まれています。

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

DECONZ_API_KEY として保存します。

---

クイックスタート

stdio（Claude Desktop）

DECONZ_HOST=192.168.1.10 DECONZ_API_KEY=abc123def deconz-mcp

ベアラー認証を使用した Streamable HTTP

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

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

---

環境変数

変数	必須	デフォルト	説明
DECONZ_HOST	はい*	—	deCONZ ゲートウェイの IP アドレスまたはホスト名
DECONZ_PORT	いいえ	80	deCONZ ゲートウェイの HTTP ポート
DECONZ_API_KEY	はい*	—	deCONZ REST API キー
DECONZ_TLS	いいえ	false	HTTPS を使用するには true に設定します
DECONZ_TLS_VERIFY	いいえ	true	false にすると、自己署名のゲートウェイ証明書を受け入れます。それ以外の値は CA バンドルへのパスとして扱われます
DECONZ_ALLOW_RUNTIME_CONFIG	いいえ	‡を参照	ゲートウェイが環境変数で指定されている場合でも、configure_deconz を公開するには true に設定します
MCP_AUTH_TOKEN	いいえ†	—	クライアントがこの MCP サーバーに送信する必要があるベアラートークン
MCP_BASE_URL	いいえ	http://<host>:<port>	公開ベース URL（OAuth 発行者 URL として使用）

* stdio を使用し、実行時に configure_deconz を呼び出す場合は不要です。
† localhost の外部に公開する HTTP トランスポートでは、設定を強く推奨します。
‡ デフォルトでは、DECONZ_HOST / DECONZ_API_KEY が設定されていない場合にのみ有効になります。ゲートウェイが環境変数で 設定されると、クライアントがこのサーバーの接続先を別のホストに変更できないよう、ツールは非公開になります。

---

CLI リファレンス

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	stdio	トランスポートモード
--host	127.0.0.1	バインドアドレス（HTTP トランスポート）
--port	8000	リッスンポート（HTTP トランスポート）
--log-level	INFO	ログの詳細度
--auth-token	$MCP_AUTH_TOKEN	MCP ベアラートークン
--base-url	$MCP_BASE_URL	OAuth 発行者 URL

トランスポートモード

モード	エンドポイント	説明
stdio	stdin/stdout	パイプベース。Claude Desktop およびローカルでの使用向け
sse	/sse, /messages/	レガシー SSE（MCP pre-2025-03-26）
streamable-http	/mcp	最新の Streamable HTTP（MCP 2025-03-26）
server	上記すべて	1 つのポートで SSE と Streamable HTTP を提供

---

認証

deCONZ API キー

deCONZ REST API キーはゲートウェイの認証情報で、URL パス（/api/<apikey>/...）の一部として送信されます。これは DECONZ_API_KEY を介してサーバー側で設定され、MCP クライアントに公開されることはありません。リクエスト URL はツールのエラーに含まれず、HTTP クライアントのリクエストログも無効化されています。ログを有効にすると、呼び出しのたびにキーが stderr に出力されるためです。

クライアントが指定するリソース ID（ライト、グループ、シーン、センサー、ルール、スケジュール、Touchlink の各 ID）は、リクエストパスに含める前に検証されます。そのため、細工された ID を使ってリソースの範囲を抜け、たとえばゲートウェイの設定や API キーの一覧にアクセスすることはできません。

MCP bearer token

MCP_AUTH_TOKEN／--auth-token オプションは、MCP サーバー自体を保護します。MCP クライアントからのすべての HTTP リクエストには、次の内容を含める必要があります。

Authorization: Bearer <token>

タイミング攻撃を防ぐため、トークンの検証には定数時間比較を使用します。localhost のみで実行する場合（デフォルトのバインド先は 127.0.0.1）、ベアラー認証は必須ではありませんが、推奨されます。

---

ツール

接続／設定

ツール	説明
configure_deconz	実行中にサーバーの接続先となる deCONZ ゲートウェイ（ホスト、ポート、API キー）を設定します。環境からゲートウェイが設定されていない場合、または DECONZ_ALLOW_RUNTIME_CONFIG=true の場合にのみ登録されます
get_gateway_config	ゲートウェイ名、ファームウェア、Zigbee チャンネル、IP、WebSocket ポートを読み取ります
set_permit_join	新しいデバイスのペアリングのために Zigbee ネットワークを開きます（0～255 秒）

ライト

ツール	説明
list_lights	オン／オフ、明るさ、到達可能性を含むすべてのライトを一覧表示します
get_light	単一のライトの詳細な JSON を取得します
set_light_state	電源、明るさ、色相、彩度、色温度、xy、エフェクト、アラートを制御します
rename_light	ライトの名前を変更します
delete_light	ゲートウェイからライトを削除します

グループ

ツール	説明
list_groups	メンバー数とアクション状態を含むすべてのグループを一覧表示します
get_group	単一のグループの詳細な JSON を取得します
create_group	新しいグループを作成します（ライトをあらかじめ追加することもできます）
set_group_action	グループ内のすべてのライトを同時に制御します
modify_group	グループの名前を変更するか、メンバーのライトを変更します
delete_group	グループを削除します（ライトは残ります）

シーン

ツール	説明
list_scenes	グループのすべてのシーンを一覧表示します
get_scene	シーンの詳細な JSON を取得します
create_scene	シーンを作成します（現在のグループ状態を保存します）
recall_scene	シーンを有効にします
store_scene	現在のグループ状態でシーンを上書きします
rename_scene	シーンの名前を変更します
delete_scene	シーンを削除します

センサー

ツール	説明
list_sensors	最新の測定値とバッテリー残量を含むすべてのセンサーを一覧表示します
get_sensor	単一のセンサーの詳細な JSON を取得します
rename_sensor	センサーの名前を変更します
set_sensor_config	センサー設定（有効状態、バッテリー残量、感度）を更新します
delete_sensor	ゲートウェイからセンサーを削除します

ルール（自動化）

ツール	説明
list_rules	ステータスとトリガー回数を含むすべての自動化ルールを一覧表示します
get_rule	ルールの詳細（条件とアクション）を取得します
create_rule	条件とアクションを指定して新しいルールを作成します
set_rule_status	ルールを有効または無効にします
delete_rule	ルールを削除します

スケジュール

ツール	説明
list_schedules	時刻指定されたすべてのスケジュールを一覧表示します
get_schedule	スケジュールの詳細な JSON を取得します
create_schedule	ISO 8601 の時刻式を指定して新しいスケジュールを作成します
set_schedule_status	スケジュールを有効または無効にします
delete_schedule	スケジュールを削除します

Touchlink

ツール	説明
touchlink_scan	近くの Zigbee デバイスを見つけるために Touchlink スキャンを開始します（約10秒）
get_touchlink_results	最後に実行した Touchlink スキャンの結果を返します
touchlink_identify	識別のために Touchlink デバイスを点滅させます
touchlink_reset	Touchlink デバイスを工場出荷時の設定にリセットします

---

リソース

リソースは読み取り専用でキャッシュ可能なスナップショットです。MCP クライアントはツール呼び出しを行わずに取得できます。

URI	説明
deconz://config	ゲートウェイ設定の JSON
deconz://lights	状態を含むすべてのライトの JSON
deconz://groups	アクション状態を含むすべてのグループの JSON
deconz://sensors	状態を含むすべてのセンサーの JSON
deconz://rules	すべての自動化ルールの JSON
deconz://schedules	すべてのスケジュールの JSON
deconz://state	ゲートウェイの完全な状態（すべてのリソースを統合）

---

プロンプト

プロンプトは、一般的なワークフローで AI をガイドする、あらかじめ用意された会話のきっかけです。

プロンプト	引数	説明
home_overview	—	完全なステータスレポート：すべてのライト、センサー、到達可能性、異常
control_lights	room（任意）	ライトのオン／オフ、明るさや色の設定
manage_scenes	group_id（任意）	シーンの作成、呼び出し、更新、削除
add_device	—	新しい Zigbee デバイスをペアリングするための手順ガイド
setup_automation	—	センサーイベントをトリガーとするルールの作成
diagnose_device	device_name（任意）	到達不能または正常に動作しないデバイスの診断
evening_routine	bedtime（デフォルトは 23:00）	夜のシーンを有効にし、ライトが消える時刻を設定

---

Claude Desktop の設定

（macOS で）~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

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

または、仮想環境にインストールした場合：

{
  "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 クライアントの設定

Streamable HTTP トランスポートの場合：

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

従来の SSE トランスポートの場合：

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

---

Docker

マルチプラットフォームイメージ（linux/amd64 + linux/arm64）は、バージョンタグがプッシュされるたびに、リリースワークフローによって GitHub Container Registry に公開されます：

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

ローカルでビルドする場合は、マルチステージの Dockerfile も含まれています。ビルダーステージでは公式の uv イメージを使って依存関係をインストールし、パッケージを wheel としてコンパイルします。ランタイムステージは python:3.14-slim で、権限のないユーザー app（uid 1000）として実行されます。

プル

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

ローカルでビルド

# 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 .

実行 — HTTP サーバー（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

実行 — 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

すぐに使える Compose ファイルは docs/docker-compose.yml にあります。次の 2 つのサービスを定義しています：

サービス	トランスポート	デフォルトで起動
deconz-mcp	ポート 8000 の server（SSE + Streamable HTTP）	はい
deconz-mcp-stdio	stdio	いいえ — --profile stdio が必要です

# 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

Claude Desktop では stdio サービスを使用します：

{
  "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

docs/k8s-deployment.yaml のマニフェストには、クラスター内でサーバーを実行するために必要なすべてのリソースが含まれています：

リソース	用途
Namespace	deconz-mcp — すべてのリソースを分離します
Secret	DECONZ_API_KEY と MCP_AUTH_TOKEN（Base64 エンコード済み）
ConfigMap	DECONZ_HOST、DECONZ_PORT、DECONZ_TLS、MCP_BASE_URL
Deployment	レプリカ 1 つ、非 root、ルート FS は読み取り専用、リソース制限
Service	ポート 80 の ClusterIP → pod 8000
Ingress	nginx／cert-manager 用のコメントアウトされたテンプレート

デプロイ

# 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

ヘルスチェック

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

Deployment では、/health に対する liveness probe と readiness probe の両方が設定されています。そのため、サーバーが応答しなくなった場合、Kubernetes が pod を自動的に再起動します。

Ingress（任意）

docs/k8s-deployment.yaml の末尾にある Ingress セクションのコメントを解除し、ホスト名を設定します。rewrite-target アノテーションは追加しないでください。エンドポイントは /mcp、/sse、/messages/ にあり、パスを変更せずに pod へ到達させる必要があります。TLS 終端は ingress コントローラーで行われます。pod は内部で常にプレーン HTTP を使用します。

---

ヘルスチェック

HTTP トランスポートでは、liveness probe が公開されます：

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

---

プロジェクト構成

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 の概要

サーバーは、以下の API カテゴリをカバーしています。

カテゴリ	エンドポイント
設定	GET /config、PUT /config（参加を許可）
ライト	GET /lights、GET /lights/<id>、PUT /lights/<id>/state、DELETE /lights/<id>
グループ	GET /groups、POST /groups、PUT /groups/<id>/action、DELETE /groups/<id>
シーン	/groups/<id>/scenes/<sid> の全 CRUD 操作（呼び出しと保存を含む）
センサー	GET /sensors、PUT /sensors/<id>/config、DELETE /sensors/<id>
ルール	/rules/<id> の全 CRUD 操作
スケジュール	/schedules/<id> の全 CRUD 操作
Touchlink	POST /touchlink/scan、識別、リセット

API の完全なリファレンスについては、deCONZ REST API ドキュメントをご覧ください。

---

データとプライバシー

予備的な評価のみです。法的助言ではありません。 詳細は以下の注記をご覧ください。

個人宅での利用

このサーバーを個人宅で実行し、居住者のみがアクセスする場合、スマートホームデバイスのデータ処理は、家庭内活動の免除（GDPR 前文 18）の対象となる可能性が高いです。この場合、GDPR は適用されず、追加のコンプライアンス対応は必要ありません。

商用または共有環境への導入

オフィス、賃貸物件、ホテル、コワーキングスペース、または他者に代わってデータを処理するあらゆる環境にこのサーバーを導入すると、家庭内活動の免除の対象外となります。その場合は、以下の対応が必要です。

• 在室センサーとモーションセンサーのデータは、個人の行動に関するデータに該当します（GDPR 第 4 条第 1 項）。処理を開始する前に、文書化された適法な根拠（第 6 条）を確立してください。
• 導入環境で居住者を大規模かつ体系的に監視する場合は、データ保護影響評価（第 35 条）を実施してください。
• 収集するデータ、その保存期間、適用する法的根拠を説明するプライバシー通知をデータ主体に提供してください。

セキュリティに関する推奨事項

リスク	推奨事項
API キーが URL パスに含まれるため、ゲートウェイ自体のアクセスログに記録されます	deCONZ API キーを定期的にローテーションし、ゲートウェイのログへのアクセスを制限してください。このサーバーは、キーを自身のログやクライアントに返すエラーに記録しません
暗号化されていない通信	ネットワークに接続する導入環境では TLS を有効にしてください（DECONZ_TLS=true）。有効な証明書を備えたリバースプロキシを使用してください。DECONZ_TLS_VERIFY=false は、信頼できるネットワーク上にある自己署名ゲートウェイ証明書の場合にのみ設定してください
MCP エンドポイントが一般にアクセス可能	ループバック以外のアドレスにバインドする場合は、必ず MCP_AUTH_TOKEN を設定してください

このソフトウェアが行わないこと

• サードパーティ、分析サービス、クラウドプロバイダーにデータを送信することはありません。
• このコードベースにテレメトリ、トラッキングピクセル、同意管理ライブラリは含まれていません。
• すべての通信は、MCP クライアント、このサーバー、ローカルの deCONZ ゲートウェイ間で行われます。

法的通知

この GDPR 評価は、予備的かつ探索的な評価として作成されたものです。法的助言を構成するものではなく、法的監査に代わるものでもありません。法的拘束力のある指針については、管轄区域内の資格を有するデータ保護弁護士にご相談ください。

---

リリース

バージョンタグをプッシュすると、リリースが作成されます。.github/workflows/release.yml は次の処理を行います。

1. タグが pyproject.toml の version と一致することを確認し、一致しない場合は早期に失敗します。
2. CI ワークフロー全体を実行します（Python 3.10～3.12 での lint、フォーマット、型チェック、テスト）。
3. SBOM とビルドの来歴情報を含めて linux/amd64 および linux/arm64 用のイメージをビルドし、ghcr.io/marcinn2/deconz-mcp にプッシュします。
4. 生成されたリリースノート、イメージダイジェスト、ビルド済みの wheel と sdist を添付して GitHub リリースを作成します。

# 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

v0.3.0-rc.1 のようにハイフンを含むタグはプレリリースとして公開され、latest イメージタグは更新されません。

v0.3.0 に対して作成されるイメージタグ：0.3.0、0.3、latest。

シークレットを設定する必要はありません。このワークフローは、組み込みの GITHUB_TOKEN を使って GHCR に認証します。最初のリリース後、イメージを匿名でプルできるようにする場合は、Packages → deconz-mcp → Package settings でパッケージの公開設定を変更してください。

---

ライセンス

Apache 2.0 — LICENSE を参照してください。

免責事項

このソフトウェアは Dresden Elektronik と提携しておらず、同社による承認も受けていません。ご自身の責任でご使用ください。いかなる種類の保証もありません。開発者は一切の責任を負いません。このソフトウェアは、私が余暇に保守している個人プロジェクトです。 詳細についてはライセンスを参照してください。