Server data from the Official MCP Registry
Unofficial MCP server for WLED LED controllers; not affiliated with the WLED project
About
Unofficial MCP server for WLED LED controllers; not affiliated with the WLED project
Security Report
The reviewed WLED MCP code is a well-structured LAN controller for LED hardware, with validated writes, read-back verification, atomic config writes, and no telemetry or credential storage in the shown files. Network access to WLED devices and local file I/O match its purpose, and no exfiltration or shell-execution patterns appear in the visible code. The main limitation is that WLED controllers have no device authentication, and the scene_tools.py and README sections were truncated, so the review is incomplete. Supply chain analysis found 6 known vulnerabilities in dependencies (1 critical, 2 high severity). Package verification found 1 issue.
5 files analyzed · 9 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"wled-mcp": {
"command": "uvx",
"args": [
"wled-mcp==0.4.0"
]
}
}
}Some servers take additional arguments. See the repository for details.
Documentation
View on GitHubFrom the project's GitHub README.
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).
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 --version -
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> -
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 |
|---|---|
| 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.
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Rea
Freeby Morluto · Developer Tools
Reverse engineer anything from your terminal or agent with one CLI and MCP server.
Paperclip
Freeby Paperclipai · Developer Tools
Trending hip-hop artist momentum scores across four cultural dimensions.
Scrapling
Freeby D4Vinci · Developer Tools
Web scraping with stealth HTTP, real browsers, and Cloudflare bypass. CSS selectors supported.
Git
Freeby Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
