Skip to main content
Glama
WLED MCP

WLED MCP

by descipar

WLED MCP

An unofficial MCP server that lets an AI agent read and control WLED LED controllers by name: power, brightness, segments, effects, palettes, presets, groups, scenes and zones. It talks to each controller's JSON API on your network, validates every change before sending it and reads it back afterwards. It runs as a subprocess of your MCP host (stdio) or as a separate HTTP service. It is not affiliated with, endorsed by or supported by the WLED project or MCPHub.

Status: early software with 0.x versions that may break between releases (CHANGELOG.md). Releases are distributed on PyPI as wled-mcp; a release that is not listed there installs from its Git tag. The server is listed in the official MCP Registry as io.github.descipar/wled-mcp. The container image is not published to GHCR. Hardware acceptance is partial: one controller on WLED 16.0.1. No support is promised (Support).

What it does

  • Self-hosted: no cloud service, account, MQTT broker or public endpoint. Controllers are a named inventory in a TOML file; nothing is discovered unless you run the opt-in wled-mcp discover.

  • State and catalogs: normalized state, capabilities and each device's own effect and palette catalogs; effects can be filtered by firmware metadata and searched by curated properties (motion, flashing, colour slots; the catalog is small).

  • Typed changes: power and brightness, a patch of selected segments or a replacement of the complete layout. Effects and palettes by name or ID, checked against the device's catalog before any write.

  • Zones: a reviewed zone file maps a physical region to devices and LED ranges; changes apply only inside the zone, otherwise they are refused before any write.

  • Presets, groups and scenes: persistent presets with snapshots, restore, portable bundles and playlists; named device groups and multi-device scenes with a dry-run plan.

  • Observe and explain (read-only): sampled live LED colours per segment, and an explanation of why a change may not show. Neither proves a cause or colour accuracy.

  • Layout preview (read-only): a static SVG of an observed or proposed 1D segment layout.

  • Temporary signals: wled_start_signal shows a colour on chosen segments of one controller for a bounded time, then restores the previous state only if nobody changed it; best effort, not a scheduler, nothing survives a restart (contract).

  • Agent guidance: safe-lighting instructions, a prompt and precise field descriptions, served identically over stdio and HTTP; the client has to pass them on to its agent.

  • Server-enforced profiles (read-only, control, full); for the HTTP service a bearer credential with Host and Origin allowlists.

All tools, each with its read-only, write or destructive hint, are listed in the tool contract.

WLED feature coverage: 60 % of the planned scope, 48 % of WLED overall (method and list).

Related MCP server: twinkly-mcp

Safety model

  • Validate first. A complete request is checked against the current device state before the first write; unknown fields and out-of-range values are rejected. Omitted fields mean "unchanged", never "reset".

  • Patch versus replace. wled_patch_segments changes only the named segments; only wled_replace_layout removes segments that are not listed.

  • Dry run and verification. dry_run=true returns the plan without writing. Writes are read back; a write that timed out is reported as possibly applied and is never retried blindly.

  • Snapshots. Overwriting or deleting a preset first stores a durable snapshot in the data directory. Restores, imports, supplied-state stores (wled_store_preset) and playlist saves change the live output before they store, and the previous lighting is not restored.

  • No hidden reach. No discovery by the server or its tools, no arbitrary endpoints or caller-supplied hosts, no silent preset overwrite (overwrite=true is required).

  • Authorization. The MCP host authorizes people; annotations are hints only. HTTP requires its own token and Host/Origin allowlists even behind a hub: hub authentication alone does not protect direct access. Keep it off the internet; see the residual risks and bounded review (one review pass, no audit).

Try it

You need uv, an MCP host that can start a stdio server and a WLED controller reachable over HTTP. Replace <version> with the version of the latest release. The commands install that release from PyPI and are for a POSIX shell; Windows is experimental (compatibility).

  1. Check the installation (no device, no configuration):

    uvx --isolated --python 3.13 --from wled-mcp==<version> wled-mcp --version
  2. Create a data directory and an inventory with one controller (contacts nothing):

    mkdir -p "$HOME/wled-mcp"
    uvx --isolated --python 3.13 --from wled-mcp==<version> wled-mcp config init --config "$HOME/wled-mcp/devices.toml" --device-id desk --device-name "Desk strip" --base-url http://<controller-address>
  3. Register the server in your MCP host with the command uvx and these arguments, each one separate, using absolute paths:

    --isolated --python 3.13 --from wled-mcp==<version> wled-mcp --transport stdio --config <absolute path>/wled-mcp/devices.toml --data-dir <absolute path>/wled-mcp

    Ask the agent to list your WLED devices (wled_list_devices). Every write tool accepts dry_run=true to preview a change without touching the lights.

More devices, the inventory format, the Git-tag route, a checksum-verified wheel, the MCPHub Registry install note and the HTTP service are in the quickstarts; updates, rollback and removal are in docs/DEPLOYMENT.md. Dependencies resolve within the declared ranges (dependency policy). GitHub releases also attach a Claude Desktop MCPB bundle (it needs uv on the PATH of Claude Desktop); it is built along with each release, not tested by the project and comes without warranty (details).

Compatibility

What the checks cover; the evidence and the firmware tiers are in docs/contract/compatibility.md. This is not a support commitment (see Support).

Area

Status

Python 3.13

supported

Linux amd64

supported

Linux arm64

supported

HTTP container image, amd64 and arm64

supported

stdio via uvx on Linux

supported

Windows

experimental

macOS

experimental

WLED 16.0.1

tested

WLED 16.x other than 16.0.1

unknown

WLED below 16.0.0, including 0.15.x

unsupported

Unsupported or unrecognized firmware is served with a warning and never refused; wled_get_state reports the tier in diagnostics.firmware_support.

Limitations

Automated tests use mocks and synthetic loopback devices. Hardware acceptance is partial: core features ran on one RGB controller with WLED 16.0.1, and an offline controller was checked once (evidence). Multi-device scenes, profiles, zones, the layout preview and CCT, RGBW or 2D controllers have no hardware run, and temporary signals ran only twice on one controller; details are in docs/VALIDATION.md.

  • No tool deletes a snapshot on request; retention pruning keeps 20 per controller.

  • On WLED 16, storing, restoring or importing a preset changes the live output, and saving a playlist may start it.

  • One writer per controller: locks are per process.

  • No inventory reload; changes need wled-mcp config validate and a restart.

  • No device authentication: WLED has none for its light API ("Anyone with your IP and port can control the lights", WLED docs). The server sends no device credentials and does not support a controller behind HTTP authentication. On one controller (WLED 16.0.1) with the settings PIN, the OTA lock or both enabled, the probed reads (state, effects, palettes, preset list and preset read) and a minimal write set (master state, segment patch, preset store and delete) worked unchanged; other writes under a lock were not run (#128, evidence).

Documentation

Document

Contents

Quickstarts

Release directory, stdio and HTTP setup, inventory format

Deployment

Both transports in detail: staging, verification, update, rollback, removal

Tool contract

Tools, parameters, results, errors and mutation semantics

WLED feature coverage

WLED features with support status, owning issue or decision, and coverage figures

Development

Local checks, build and launch, including PowerShell

Validation

Automated checks, opt-in hardware checks, recorded evidence, known limitations

Contract examples

Synthetic request, result and snapshot examples

Support

There is no support commitment. Before opening an issue, see the troubleshooting guide. Questions and problems go to GitHub issues, which are answered best effort, without any commitment to respond or fix. There is no security support; see SECURITY.md.

The server collects no telemetry, so the project does not know whether it is used. If you run it, a short note on how you use it and what is missing is welcome as a usage feedback issue. Please leave out secrets, hostnames and addresses.

Project and contributing

Roadmap and maintainer documents are in docs/PROJECT.md. How to report problems and propose changes is in CONTRIBUTING.md.

How this project is developed

The maintainer develops this project with coding agents that follow a documented workflow (AGENTS.md, docs/AGENT-WORKFLOW.md, docs/DECISIONS.md). Human contributions do not need this workflow.

License

Licensed under the Apache License 2.0. Redistributions, including modified versions, must retain the copyright and attribution notice in NOTICE. The project is provided as is, without security support; see SECURITY.md.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server that enables AI agents to control Twinkly lights through natural language, supporting operations like on/off, color, brightness, and effects.
      14
      13 npm
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      A LAN-first, cloud-fallback MCP server for controlling Govee smart devices by name. It enables AI agents or MCP clients to manage lights, plugs, and appliances with commands like power, brightness, color, and scenes.
      51 PyPI
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables an AI agent to control one or more remote GPIO agents through a conversation by proxying tool calls to their REST APIs. It supports API-key authentication, LAN discovery, and both stdio and Streamable HTTP transports.
      18
      318 npm
      1
      MIT