WLED MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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_signalshows 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_segmentschanges only the named segments; onlywled_replace_layoutremoves segments that are not listed.Dry run and verification.
dry_run=truereturns 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=trueis 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).
Check the installation (no device, no configuration):
uvx --isolated --python 3.13 --from wled-mcp==<version> wled-mcp --versionCreate 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>Register the server in your MCP host with the command
uvxand 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-mcpAsk the agent to list your WLED devices (
wled_list_devices). Every write tool acceptsdry_run=trueto 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 validateand 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 |
Release directory, stdio and HTTP setup, inventory format | |
Both transports in detail: staging, verification, update, rollback, removal | |
Tools, parameters, results, errors and mutation semantics | |
WLED features with support status, owning issue or decision, and coverage figures | |
Local checks, build and launch, including PowerShell | |
Automated checks, opt-in hardware checks, recorded evidence, known limitations | |
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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
Control your existing Philips lights, Sonos speakers, Roborock vacuums and other supported devices through Port OS cloud. Give ChatGPT, Claude and other MCP-compatible assistants access to the devices you connect. Turn off the living room lights, play music on your speakers, adjust the thermostat, run a vacuum in a room, check a camera snapshot or find a connected tracker. Available actions depend on your linked provider accounts and each device’s supported capabilities. Port OS runs in the cloud; no local server is required. You choose the account, device and capability permissions each assistant receives. Device operations require user OAuth; public tool discovery does not grant device access. Port OS is in alpha. Setup: https://portoperatingsystem.com/docs/getting-started/ Support: https://portoperatingsystem.com/contact/
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to control a local LedFX instance through natural language, allowing management of LED devices, virtuals, effects, scenes, palettes, and playlists.834MIT
- AlicenseAqualityDmaintenanceMCP server that enables AI agents to control Twinkly lights through natural language, supporting operations like on/off, color, brightness, and effects.1413 npmISC
- AlicenseNot gradedqualityDmaintenanceA 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 PyPIMIT
- AlicenseAqualityBmaintenanceEnables 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.18318 npm1MIT