zencontrol-cloud-mcp

MCP server for ZenControl DALI-2 lighting control via the ZenControl Cloud API.

Overview

zencontrol-cloud-mcp enables AI assistants — such as Claude, Cursor, and other MCP-compatible clients — to discover and control ZenControl DALI-2 lighting systems through natural language.

Built on the Model Context Protocol (MCP) with FastMCP, the server supports two transports:

• stdio — for local, single-user setups (Claude Desktop, Cursor, etc.)

• StreamableHTTP — for hosted / multi-user deployments

Features

Prerequisites

• Python 3.11+

• ZenControl Cloud account with API credentials (client_id and client_secret) — see How to use OAuth 2.0 authentication for zencontrol cloud APIs for instructions on obtaining credentials

• uv package manager (recommended) or pip

Quick Start

1. Set your credentials:

   export ZENCONTROL_CLIENT_ID=your_client_id
   export ZENCONTROL_CLIENT_SECRET=your_client_secret

2. Run with uvx:

   uvx zencontrol-cloud-mcp

   On first launch a browser window will open so you can log in to ZenControl. After that, tokens are cached and refreshed automatically.

Configuration

Claude Desktop (stdio mode)

Add the following to your Claude Desktop configuration file:

{
  "mcpServers": {
    "zencontrol": {
      "command": "uvx",
      "args": ["zencontrol-cloud-mcp"],
      "env": {
        "ZENCONTROL_CLIENT_ID": "your_client_id",
        "ZENCONTROL_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

HTTP mode (hosted)

Start the server on a network port:

uvx zencontrol-cloud-mcp --transport streamable-http --port 9000

Then point your MCP client at the HTTP endpoint:

{
  "mcpServers": {
    "zencontrol": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

Environment Variables

Authentication

The server uses OAuth 2.0 Authorization Code flow to authenticate with the ZenControl Cloud API.

1. On first run the server opens your default browser so you can log in.

2. Tokens are stored encrypted in a platform-appropriate location (via platformdirs).

3. Tokens are refreshed automatically when they expire — you should rarely need to re-authenticate.

Usage Examples

Typical interactions with an AI assistant:

User: "What sites do I have access to?"
→ Calls list_sites

User: "Show me the structure of the Main Office site"
→ Calls get_site_details

User: "Turn on all lights in the Lobby group"
→ Calls control_light(target_type="group", target_id="...", action="on")

User: "Set the office lights to 50% brightness"
→ Calls control_light(target_type="group", target_id="...", action="set_level", level=50)

User: "Change the lobby to warm white (3000K)"
→ Calls set_colour(target_type="group", target_id="...", mode="temperature", kelvin=3000)

Core Tool Families

• Site discovery: list_sites, get_site_details

• Topology inventory: list_groups, list_devices, list_gateways, list_device_locations

• Lighting control: control_light, set_colour, set_profile

• Live telemetry: get_live_light_levels, get_sensor_readings, get_system_variables

• Diagnostics: get_device_health

• Scope controls: set_scope, get_scope, clear_scope

Safe Control Workflow

1. Start with list_sites.

2. Resolve a concrete target with get_site_details or list_groups.

3. Prefer controlling groups over individual devices.

4. Use moderate levels first (for example, 30-50%) before full output.

5. Use scope controls to avoid cross-site mistakes in multi-site environments.

Troubleshooting

• Required environment variable(s) not set:

  • Set ZENCONTROL_CLIENT_ID and ZENCONTROL_CLIENT_SECRET for stdio mode.

• HTTP 401 on live endpoints:

  • Verify account entitlement for Live API and valid token scope.

• HTTP 403 on diagnostics:

  • Account may not have access to diagnostics endpoints.

• get_site_details parsing inconsistencies:

  • This server tolerates both label payload shapes ({"value": "..."} and plain strings).

Architecture

┌─────────────────────┐     stdio / StreamableHTTP     ┌─────────────────────┐
│     MCP Client      │ ──────────────────────────────▶ │ zencontrol-cloud-mcp│
│ (Claude, Cursor, …) │                                │   FastMCP Server    │
└─────────────────────┘                                └──────────┬──────────┘
                                                                  │
                                                    REST + Live API│
                                                                  ▼
                                                       ┌──────────────────┐
                            ┌──────────────────┐       │    ZenControl    │
                            │    Encrypted     │◀─────▶│    Cloud API     │
                            │   Token Store    │       └──────────────────┘
                            └──────────────────┘

Development

git clone https://github.com/oWretch/zencontrol-cloud-mcp.git
cd zencontrol-cloud-mcp
uv sync

# Lint & format
uv run ruff check src/
uv run ruff format --check src/

# Run tests
uv run pytest

# Generate full API docs (Markdown)
uv run python scripts/generate_docs.py

Generated documentation entry points:

• docs/reference/api.md

See CONTRIBUTING.md for full guidelines.

API Payload Compatibility Notes

Some ZenControl payloads can represent labels in two shapes:

• Wrapped sync field: { "value": "Office", "state": "OK", "error": null }

• Plain string: "Office"

The server accepts both formats for label fields (for example, tenancy and floor labels) so tools such as get_site_details remain robust across mixed API responses.

License

This project is licensed under the Apache License 2.0.