Mcp Server For Deconz Server

deConz MCP 服务

一个 MCP（Model Context Protocol） 服务，可将 deCONZ REST API 提供给 AI 助手。通过自然语言控制 Zigbee 灯具、传感器、群组、场景、规则和计划。

支持 stdio、SSE 和 Streamable HTTP 传输方式。HTTP 传输方式受可配置的 Bearer 令牌保护。

---

要求

• Python ≥ 3.10
• uv（推荐）或 pip
• 正在运行的 deCONZ / Phoscon 网关，以及 ConBee 或 RaspBee 适配器
• 有效的 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. 前往 菜单 → 设置 → 网关 → 高级。
3. 点击 验证应用 — 网络将开放 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

使用 Bearer 身份验证的 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	设置为 true 以使用 HTTPS
DECONZ_TLS_VERIFY	否	true	false 表示接受自签名网关证书；其他任何值均视为 CA 证书包的路径
DECONZ_ALLOW_RUNTIME_CONFIG	否	参见‡	即使网关配置来自环境变量，也设置为 true 以公开 configure_deconz
MCP_AUTH_TOKEN	否†	—	客户端必须向此 MCP 服务发送的 Bearer 令牌
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 Bearer 令牌
--base-url	$MCP_BASE_URL	OAuth 颁发者 URL

传输模式

模式	端点	说明
stdio	stdin/stdout	基于管道 — 用于 Claude Desktop 和本地使用
sse	/sse、/messages/	旧版 SSE（MCP 2025-03-26 之前）
streamable-http	/mcp	现代 Streamable HTTP（MCP 2025-03-26）
server	以上全部	在同一端口上提供 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），Bearer 身份验证是可选的，但建议启用。

---

工具

连接 / 配置

工具	描述
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	获取规则的完整 JSON 详情（条件 + 操作）
create_rule	创建包含条件和操作的新规则
set_rule_status	启用或停用规则
delete_rule	删除规则

定时计划

工具	描述
list_schedules	列出所有定时计划
get_schedule	获取定时计划的完整 JSON 详情
create_schedule	使用 ISO 8601 时间表达式创建新的定时计划
set_schedule_status	启用或停用定时计划
delete_schedule	删除定时计划

Touchlink

工具	描述
touchlink_scan	启动 Touchlink 扫描（约 10 秒），查找附近的 Zigbee 设备
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 配置

添加到 ~/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"
      }
    }
  }
}

或者，如果安装在虚拟环境中：

{
  "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。该文件定义了两项服务：

服务	传输方式	默认启动
deconz-mcp	server（SSE + Streamable HTTP），端口 8000	是
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 用户、只读 root 文件系统、资源限制
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 配置了存活探针和就绪探针，因此如果服务无响应，Kubernetes 会自动重启 pod。

Ingress（可选）

取消 docs/k8s-deployment.yaml 底部 Ingress 部分的注释，并设置你的主机名。不要添加 rewrite-target 注解：端点位于 /mcp、/sse 和 /messages/，必须保留原路径到达 pod。TLS 终止由 ingress 控制器处理；pod 内部始终使用纯 HTTP 通信。

---

健康检查

HTTP 传输方式会提供存活探针：

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. 构建适用于 linux/amd64 和 linux/arm64 的镜像，附带 SBOM 和构建来源证明，并推送到 ghcr.io/marcinn2/deconz-mcp。
4. 创建 GitHub release，附上自动生成的说明、镜像摘要以及构建好的 wheel 和 sdist。

# 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 无关，也未获其认可。使用风险由您自行承担。本软件不提供任何形式的保证。开发者不承担任何责任。本软件是我在业余时间维护的个人项目。 更多信息请参阅许可证。