Back to Browse

Wled MCP Server

Developer ToolsModerate5.6MCP RegistryLocal
Free

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

5.6
Moderate5.6Moderate Risk

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.

HTTP Network Access

Connects to external APIs or services over the internet.

File System Read

Reads files on your machine. Normal for tools that analyze or process local data.

File System Write

Writes or modifies files on your machine. Check that this is expected for the tool.

env_vars

Check that this permission is expected for this type of plugin.

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 GitHub

From 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_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).

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).

AreaStatus
Python 3.13supported
Linux amd64supported
Linux arm64supported
HTTP container image, amd64 and arm64supported
stdio via uvx on Linuxsupported
Windowsexperimental
macOSexperimental
WLED 16.0.1tested
WLED 16.x other than 16.0.1unknown
WLED below 16.0.0, including 0.15.xunsupported

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

DocumentContents
QuickstartsRelease directory, stdio and HTTP setup, inventory format
DeploymentBoth transports in detail: staging, verification, update, rollback, removal
Tool contractTools, parameters, results, errors and mutation semantics
WLED feature coverageWLED features with support status, owning issue or decision, and coverage figures
DevelopmentLocal checks, build and launch, including PowerShell
ValidationAutomated checks, opt-in hardware checks, recorded evidence, known limitations
Contract examplesSynthetic 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!