deConz MCP

Servidor MCP para o servidor deConz desenvolvido pela Dresden Elektronik (ponte entre plataformas de automação residencial inteligente e redes Zigbee sem fio)

GitHub

Documentação

Servidor deConZ MCP

Um servidor MCP (Model Context Protocol) que expõe a API REST do deCONZ para assistentes de IA. Controle luzes Zigbee, sensores, grupos, cenas, regras e agendamentos por meio de linguagem natural.

Suporta os transportes stdio, SSE e Streamable HTTP. Os transportes HTTP são protegidos por um token de portador (bearer token) configurável.

Requisitos

Python ≥ 3.10
uv (recomendado) ou pip
Um gateway deCONZ / Phoscon em execução com um adaptador ConBee ou RaspBee
Uma chave de API REST do deCONZ válida (veja Obtendo uma chave de API)

Instalação

# Clone the repository
git clone https://github.com/your-org/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 .

Obtendo uma chave de API

Abra o Phoscon App no seu navegador (geralmente http://<gateway-ip>/pwa).
Vá em Menu → Configurações → Gateway → Avançado.
Clique em Autenticar aplicativo — isso abre a rede por 60 segundos.
Dentro desses 60 segundos, execute:

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

A resposta contém sua chave de API:

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

Armazene-a como DECONZ_API_KEY.

Início rápido

stdio (Claude Desktop)

DECONZ_HOST=192.168.1.10 DECONZ_API_KEY=abc123def deconz-mcp

Streamable HTTP com autenticação de portador

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 combinados

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

Variáveis de ambiente

Variável	Obrigatória	Padrão	Descrição
`DECONZ_HOST`	Sim*	—	IP ou nome de host do gateway deCONZ
`DECONZ_PORT`	Não	`80`	Porta HTTP do gateway deCONZ
`DECONZ_API_KEY`	Sim*	—	Chave da API REST do deCONZ
`DECONZ_TLS`	Não	`false`	Defina `true` para usar HTTPS
`MCP_AUTH_TOKEN`	Não†	—	Token de portador que os clientes devem enviar a este servidor MCP
`MCP_BASE_URL`	Não	`http://<host>:<port>`	URL base pública (usada como URL do emissor OAuth)

* Não obrigatório ao usar stdio e chamar configure_deconz em tempo de execução.
† Fortemente recomendado para transportes HTTP expostos além de localhost.

Referência da 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]

Flag	Padrão	Descrição
`--transport`	`stdio`	Modo de transporte
`--host`	`127.0.0.1`	Endereço de bind (transportes HTTP)
`--port`	`8000`	Porta de escuta (transportes HTTP)
`--log-level`	`INFO`	Nível de detalhe do log
`--auth-token`	`$MCP_AUTH_TOKEN`	Token de portador do MCP
`--base-url`	`$MCP_BASE_URL`	URL do emissor OAuth

Modos de transporte

Modo	Endpoint(s)	Descrição
`stdio`	stdin/stdout	Baseado em pipe — para Claude Desktop e uso local
`sse`	`/sse`, `/messages/`	SSE legado (MCP anterior a 2025-03-26)
`streamable-http`	`/mcp`	Streamable HTTP moderno (MCP 2025-03-26)
`server`	todos os acima	SSE + Streamable HTTP em uma única porta

Autenticação

Chave da API do deCONZ

A chave da API REST do deCONZ é uma credencial do gateway que viaja como parte do caminho da URL (/api/<apikey>/...). Ela é configurada no lado do servidor por meio de DECONZ_API_KEY e nunca é exposta aos clientes MCP.

Token de portador do MCP

A opção MCP_AUTH_TOKEN / --auth-token protege o próprio servidor MCP. Toda solicitação HTTP de um cliente MCP deve incluir:

Authorization: Bearer <token>

O token é verificado com uma comparação de tempo constante para evitar ataques de timing. Ao executar apenas em localhost (bind padrão 127.0.0.1), a autenticação de portador é opcional, mas recomendada.

Ferramentas

Conexão / configuração

Ferramenta	Descrição
`configure_deconz`	Aponta o servidor para um gateway deCONZ em tempo de execução (host, porta, chave de API)
`get_gateway_config`	Lê nome do gateway, firmware, canal Zigbee, IP, porta WebSocket
`set_permit_join`	Abre a rede Zigbee para pareamento de novos dispositivos (0–255 segundos)

Luzes

Ferramenta	Descrição
`list_lights`	Lista todas as luzes com estado ligado/desligado, brilho e acessibilidade
`get_light`	Detalhes JSON completos de uma única luz
`set_light_state`	Controla energia, brilho, matiz, saturação, temperatura de cor, xy, efeito, alerta
`rename_light`	Renomeia uma luz
`delete_light`	Remove uma luz do gateway

Grupos

Ferramenta	Descrição
`list_groups`	Lista todos os grupos com contagem de membros e estado da ação
`get_group`	Detalhes JSON completos de um único grupo
`create_group`	Cria um novo grupo (opcionalmente pré-populado com luzes)
`set_group_action`	Controla todas as luzes de um grupo simultaneamente
`modify_group`	Renomeia um grupo ou altera suas luzes membros
`delete_group`	Exclui um grupo (as luzes permanecem)

Cenas

Ferramenta	Descrição
`list_scenes`	Lista todas as cenas de um grupo
`get_scene`	Detalhes JSON completos de uma cena
`create_scene`	Cria uma cena (captura o estado atual do grupo)
`recall_scene`	Ativa uma cena
`store_scene`	Sobrescreve uma cena com o estado atual do grupo
`rename_scene`	Renomeia uma cena
`delete_scene`	Exclui uma cena

Sensores

Ferramenta	Descrição
`list_sensors`	Lista todos os sensores com leituras mais recentes e níveis de bateria
`get_sensor`	Detalhes JSON completos de um único sensor
`rename_sensor`	Renomeia um sensor
`set_sensor_config`	Atualiza a configuração do sensor (habilitado, nível de bateria, sensibilidade)
`delete_sensor`	Remove um sensor do gateway

Regras (automações)

Ferramenta	Descrição
`list_rules`	Lista todas as regras de automação com status e contagens de gatilho
`get_rule`	Detalhes JSON completos (condições + ações) de uma regra
`create_rule`	Cria uma nova regra com condições e ações
`set_rule_status`	Habilita ou desabilita uma regra
`delete_rule`	Exclui uma regra

Agendamentos

Ferramenta	Descrição
`list_schedules`	Lista todos os agendamentos programados
`get_schedule`	Detalhes JSON completos de um agendamento
`create_schedule`	Cria um novo agendamento com expressão de tempo ISO 8601
`set_schedule_status`	Habilita ou desabilita um agendamento
`delete_schedule`	Exclui um agendamento

Touchlink

Ferramenta	Descrição
`touchlink_scan`	Inicia um escaneamento Touchlink (~10 s) para encontrar dispositivos Zigbee próximos
`get_touchlink_results`	Retorna resultados do último escaneamento Touchlink
`touchlink_identify`	Faz um dispositivo Touchlink piscar para identificação
`touchlink_reset`	Restaura um dispositivo Touchlink para as configurações de fábrica

Recursos

Recursos são instantâneos somente leitura e armazenáveis em cache que os clientes MCP podem buscar sem emitir chamadas de ferramenta.

URI	Descrição
`deconz://config`	Configuração do gateway em JSON
`deconz://lights`	Todas as luzes com estado em JSON
`deconz://groups`	Todos os grupos com estado de ação em JSON
`deconz://sensors`	Todos os sensores com estado em JSON
`deconz://rules`	Todas as regras de automação em JSON
`deconz://schedules`	Todos os agendamentos em JSON
`deconz://state`	Estado completo do gateway (todos os recursos combinados)

Prompts

Prompts são iniciadores de conversa pré-construídos que guiam a IA por fluxos de trabalho comuns.

Prompt	Argumentos	Descrição
`home_overview`	—	Relatório de status completo: todas as luzes, sensores, acessibilidade, anomalias
`control_lights`	`room` (opcional)	Liga/desliga luzes, define brilho ou cor
`manage_scenes`	`group_id` (opcional)	Cria, recupera, atualiza ou exclui cenas
`add_device`	—	Guia passo a passo para parear um novo dispositivo Zigbee
`setup_automation`	—	Cria uma regra acionada por um evento de sensor
`diagnose_device`	`device_name` (opcional)	Diagnostica dispositivos inacessíveis ou com mau comportamento
`evening_routine`	`bedtime` (padrão `23:00`)	Ativa uma cena noturna e agenda o desligamento das luzes

Configuração do Claude Desktop

Adicione a ~/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"
      }
    }
  }
}

Ou se instalado em um ambiente virtual:

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

Configuração do cliente HTTP

Para transporte Streamable HTTP:

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

Para transporte SSE legado:

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

Docker

Uma imagem multi-plataforma pré-compilada (linux/amd64 + linux/arm64) é publicada no registro:

registry.mne.pl/deconz-mcp:latest
registry.mne.pl/deconz-mcp:0.1.0

Um Dockerfile multi-estágio também está incluído se você preferir compilar localmente. O estágio de build usa a imagem oficial uv para instalar dependências e compilar o pacote como uma wheel; o estágio de runtime é python:3.12-slim (57 MB no total).

Pull

docker pull registry.mne.pl/deconz-mcp:latest

Compilar localmente

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

# Multi-platform push (requires a buildx builder with multi-platform support)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag registry.mne.pl/deconz-mcp:latest \
  --tag registry.mne.pl/deconz-mcp:0.1.0 \
  --push .

Executar — servidor 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 \
  registry.mne.pl/deconz-mcp:latest

Executar — stdio

docker run -i \
  -e DECONZ_HOST=192.168.1.10 \
  -e DECONZ_API_KEY=abc123def \
  registry.mne.pl/deconz-mcp:latest --transport stdio

Docker Compose

Um arquivo Compose pronto para uso está em docs/docker-compose.yml. Ele define dois serviços:

Serviço	Transporte	Iniciado por padrão
`deconz-mcp`	`server` (SSE + Streamable HTTP) na porta 8000	Sim
`deconz-mcp-stdio`	`stdio`	Não — requer `--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
docker compose -f docs/docker-compose.yml up

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

Use o serviço stdio no 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

O manifesto em k8s/deployment.yaml contém todos os recursos necessários para executar o servidor em um cluster:

Recurso	Finalidade
`Namespace`	`deconz-mcp` — isola todos os recursos
`Secret`	`DECONZ_API_KEY` e `MCP_AUTH_TOKEN` (codificados em base64)
`ConfigMap`	`DECONZ_HOST`, `DECONZ_PORT`, `DECONZ_TLS`, `MCP_BASE_URL`
`Deployment`	1 réplica, não-root, sistema de arquivos raiz somente leitura, limites de recursos
`Service`	`ClusterIP` na porta 80 → pod 8000
`Ingress`	Template comentado para nginx / cert-manager

Implantar

# 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 k8s/deployment.yaml

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

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

Verificação de saúde

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

O Deployment configura tanto uma sonda de liveness quanto uma sonda de readiness contra /health, para que o Kubernetes reinicie automaticamente o pod se o servidor ficar sem resposta.

Ingress (opcional)

Descomente a seção Ingress na parte inferior de k8s/deployment.yaml e defina seu nome de host. A terminação TLS ocorre no controlador de ingress; o pod sempre fala HTTP simples internamente.

Verificação de saúde

Os transportes HTTP expõem uma sonda de liveness:

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

Estrutura do projeto

deConz-mcp/
├── Dockerfile                      # Multi-stage image build
├── pyproject.toml                  # Package metadata and dependencies
├── uv.lock                         # Locked dependency versions
├── README.md
├── docs/
│   └── docker-compose.yml          # Compose services (HTTP + stdio)
├── k8s/
│   └── deployment.yaml             # Kubernetes: Namespace, Secret, ConfigMap,
│                                   #   Deployment, Service, Ingress (template)
└── 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

Visão geral da API do deCONZ

O servidor cobre estas categorias de API:

Categoria	Endpoints
Config	`GET /config`, `PUT /config` (permitir entrada)
Luzes	`GET /lights`, `GET /lights/<id>`, `PUT /lights/<id>/state`, `DELETE /lights/<id>`
Grupos	`GET /groups`, `POST /groups`, `PUT /groups/<id>/action`, `DELETE /groups/<id>`
Cenas	CRUD completo em `/groups/<id>/scenes/<sid>` incluindo recall e store
Sensores	`GET /sensors`, `PUT /sensors/<id>/config`, `DELETE /sensors/<id>`
Regras	CRUD completo em `/rules/<id>`
Agendamentos	CRUD completo em `/schedules/<id>`
Touchlink	`POST /touchlink/scan`, identify, reset

Para a referência completa da API, consulte a documentação da API REST do deCONZ.

Dados e Privacidade

Apenas avaliação preliminar — não é aconselhamento jurídico. Consulte as notas completas abaixo.

Uso doméstico pessoal

Quando este servidor é executado em uma residência particular e é acessado apenas pelos moradores, o processamento de dados de dispositivos de casa inteligente provavelmente é coberto pela isenção doméstica (Considerando 18 do RGPD). Nesse cenário, o RGPD não se aplica e nenhuma etapa adicional de conformidade é necessária.

Implantações comerciais ou compartilhadas

Implantar este servidor em escritórios, imóveis para aluguel, hotéis, espaços de coworking ou qualquer ambiente onde você processa dados em nome de outras pessoas o tira da isenção doméstica. Nesses casos:

Dados de sensores de presença e movimento constituem dados comportamentais pessoais (Art. 4(1) do RGPD). Estabeleça uma base legal documentada (Art. 6) antes de processá-los.
Realize uma Avaliação de Impacto sobre a Proteção de Dados (Art. 35) se a implantação envolver monitoramento sistemático de ocupantes em grande escala.
Forneça um aviso de privacidade aos titulares dos dados descrevendo o que é coletado, por quanto tempo e sob qual base legal.

Recomendações de segurança

Risco	Recomendação
Chave da API exposta em caminhos de URL e logs de acesso do servidor	Gire a chave da API deCONZ periodicamente; restrinja o acesso aos logs do gateway
Transporte não criptografado	Habilite TLS para qualquer implantação voltada à rede (`DECONZ_TLS=true`); use um proxy reverso com certificado válido
Endpoint MCP acessível publicamente	Sempre defina `MCP_AUTH_TOKEN` ao vincular a um endereço não loopback

O que este software NÃO faz

Nenhum dado é enviado a terceiros, serviços de análise ou provedores de nuvem.
Nenhuma telemetria, pixel de rastreamento ou bibliotecas de consentimento estão presentes neste código.
Toda a comunicação permanece entre o cliente MCP, este servidor e o gateway deCONZ local.

Aviso legal

Esta avaliação de GDPR foi gerada como uma avaliação preliminar e exploratória. Não constitui aconselhamento jurídico e não substitui uma auditoria legal. Para orientação vinculativa, consulte um advogado de proteção de dados qualificado em sua jurisdição.

Licença

Apache 2.0 — veja Licença.

Isenção de responsabilidade

Este software não é afiliado ou endossado pela Dresden Elektronik. Use por sua conta e risco. Não vem com nenhuma garantia de qualquer tipo. Não há responsabilidade para o desenvolvedor. Este software é um projeto pessoal que mantenho no meu tempo livre. Consulte a licença para mais informações.