
plaiiinlight-mcp
io.github.nebeleben/plaiiinlight-mcp
Control PlaiiinLight LED lamps on your local network: colour, effects, images, scenes, firmware.
Documentation
plaiiinlight-mcp — PlaiiinLight lamps for any MCP program
An MCP server that lets an AI assistant work with your PlaiiinLight lamps from a conversation: switch and colour them, write and preview new light effects, draw pictures, save scenes, keep several lamps in step and check them for firmware updates.
It runs entirely on your computer and talks to the lamps over your own network. You decide, per lamp, what the assistant is allowed to do.
It is listed in the official MCP Registry as
io.github.nebeleben/plaiiinlight-mcp, so MCP programs that browse the registry can find it by name.
Using Claude Code or the ChatGPT app? They have their own plugins, which install in one step: plaiiin-light-claudecode and plaiiin-light-chatgpt. This package is for everything else that speaks MCP.
Requirements
- macOS, Linux or Windows. It is developed and tested on macOS. On Linux and Windows it runs with two differences, which we have not tested ourselves: lamp keys are kept in a file only you can read instead of the Keychain, and a share link cannot be read from the clipboard — give the assistant the link itself or a screenshot of the QR code.
- Node.js 20 or newer (
node --version). - An AI program that can start a local MCP server (often called a "stdio" or "command" server).
- A PlaiiinLight lamp with firmware 2.8 or newer, on the same network as your computer.
- No PlaiiinLight app is needed to start: lamps that nobody has paired yet are found on the network and can be used right away. To give the assistant access to a lamp that is paired, you need the PlaiiinLight app (macOS, iPhone, iPad or Android) to create a key for it.
Setup — the one thing every program needs
Every MCP program has a place where you list servers. Add one that runs this command:
npx -y plaiiinlight-mcp --profile <name>
In most programs that is an entry with the command npx and the arguments
-y, plaiiinlight-mcp, --profile, <name>. Where the entry goes, and its exact form, is up to
your program; see its documentation on MCP servers. A few examples follow below.
--profile is required, and the server will not start without it. Pick a short name for the
program you are setting up — gemini, cursor, anything in lowercase letters, digits and hyphens.
Each profile has its own lamp list and its own keys, so a lamp key you gave to one AI program is
not quietly used by another. Use a different name in each program.
If the server does not start, the program probably cannot find Node.js: on a Mac, programs started
from the Finder do not see your shell's PATH. Run which npx in a terminal, use that full path as the
command, and also put its folder on the entry's PATH — npx itself needs to find node there.
In the JSON forms below that is one more line, for example:
"env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin" }
with /opt/homebrew/bin replaced by the folder which npx printed.
To stay on one version, name it: plaiiinlight-mcp@0.3.0. Without a version, a current npm picks
up a new release the next time the server starts (very old npm keeps the first one it downloaded).
Examples
These are taken from each program's own documentation as of November 2026. We have not tested them in these programs, and settings formats change — if one does not work, your program's documentation is right and this page is out of date.
Gemini CLI
~/.gemini/settings.json:
{
"mcpServers": {
"plaiiinlight": {
"command": "npx",
"args": ["-y", "plaiiinlight-mcp", "--profile", "gemini"]
}
}
}
Check with /mcp. (Its successor, Antigravity CLI, reads the same mcpServers entry from
~/.gemini/config/mcp_config.json.)
Cursor
~/.cursor/mcp.json:
{
"mcpServers": {
"plaiiinlight": {
"type": "stdio",
"command": "npx",
"args": ["-y", "plaiiinlight-mcp", "--profile", "cursor"]
}
}
}
VS Code (GitHub Copilot)
Command Palette → MCP: Add Server → Command (stdio), or ~/.copilot/mcp-config.json:
{
"mcpServers": {
"plaiiinlight": {
"type": "stdio",
"command": "npx",
"args": ["-y", "plaiiinlight-mcp", "--profile", "vscode"],
"tools": ["*"]
}
}
}
Claude Desktop
Settings → Developer → Edit Config
(~/Library/Application Support/Claude/claude_desktop_config.json), then quit Claude Desktop
completely and open it again:
{
"mcpServers": {
"plaiiinlight": {
"command": "npx",
"args": ["-y", "plaiiinlight-mcp", "--profile", "claude-desktop"]
}
}
}
LM Studio
Program tab → Install → Edit mcp.json:
{
"mcpServers": {
"plaiiinlight": {
"command": "npx",
"args": ["-y", "plaiiinlight-mcp", "--profile", "lmstudio"]
}
}
}
With a local model, mind the context size: the server has about fifty tools.
Giving an assistant access to a lamp
A lamp that nobody has paired yet is found on the network and can be used right away, with full access.
For a lamp you have paired in the PlaiiinLight app, you create a key for the assistant:
- In the app: Share → New Share → pick the lamp.
- Access: AI.
- Choose what the assistant may do. Each of these is a separate switch: control (power, colour, brightness, modes), scripts, drawings, scenes, live streaming, firmware update, rename, and reading the swarm.
- Optionally limit the brightness, and allow the assistant to act only while the lamp is switched on.
- Create. The app shows a link and a QR code.
Copy the link and tell the assistant to add the lamp; the server reads the link from the clipboard, so the key does not pass through the chat. A saved screenshot of the QR code works too. (Reading the clipboard works on macOS; elsewhere use the screenshot, or paste the link — a pasted link does pass through the chat.)
The lamp itself enforces these permissions. You can change them, or revoke the key, in the app's Share tab at any time. An AI key cannot be used by the apps.
Keys are not shared between profiles. A key added under --profile gemini is not available
under --profile cursor, nor to the Claude Code or ChatGPT plugins. Create a separate AI share
for each program.
What it does and what it talks to
- Lamps and access — find lamps, list them with their state, add a shared lamp, forget one.
- Control — power, colour, brightness, mode, play, next, previous, stop.
- Effects — write an effect script, preview it locally as a picture of its first frames, check and compile it on the lamp, upload it, tune it, copy it to other lamps, keep a local library.
- Images — draw pixel art or send a PNG, save, show, label, copy, delete.
- Scenes — capture what a lamp shows, edit, activate, copy between lamps.
- Streaming — GIFs, PNG frames or a script, live to the lamp.
- Firmware — compare lamps with the newest release and install it, one lamp at a time, with a checksum check.
Guides. Doing these jobs well takes some know-how — how an effect script is written and
tested, how access works. The server carries five guides (compose-effect, draw-image, scenes,
fleet-ota, lamp-access) and offers them three ways, because programs differ in what they support:
through the tool lamps_guide, as MCP prompts, and as MCP resources
(plaiiin-lamps://skills/<name>). The assistant is told to read the matching guide before it
starts such a job.
The server talks to exactly two things:
- your lamps, over plain HTTP and WebSocket on your local network;
- GitHub, to read and download the firmware releases of
nebeleben/plaiiin-light, and only when you ask about or install firmware.
There is no hosted service, no account and no telemetry. Your conversation with the assistant itself goes wherever your AI program sends it; that includes what the tools report back, such as lamp names, states and preview pictures. Lamp keys are not part of that, unless you paste a share link into the chat yourself.
Where things are stored
With --profile <name>:
- Keys: the macOS Keychain, service
plaiiin-lamp-mcp-<name>, one entry per lamp. On Linux and Windows:~/.plaiiin/lamps-<name>/secrets.json, readable only by you. ~/.plaiiin/lamps-<name>/fleet.json— the lamps this profile knows. No secrets.~/.plaiiin/lamps-<name>/library/— effects, images and scenes you saved to the local library.
Safety
- Two steps for anything destructive. Deleting, overwriting, renaming, forgetting a lamp and firmware updates first return a summary; the assistant shows it to you and acts only after you agree. Whether your AI program additionally asks before a tool runs is that program's setting.
- An AI key only allows what you granted, and the lamp firmware enforces it, not just this server.
- Effect preview sandbox.
effect_previewruns untrusted scripts in a separate Node process under the Node permission model (--permission, reading only its own worker file), with a heap cap and a timeout; the script itself runs in avmcontext holding only the shade runtime (norequire,processorfetch). The permission model blocks file-system access, child processes and worker threads, but it does not restrict network access: a script that escaped thevmcontext could still open sockets. Treat previews of scripts from strangers accordingly. - Share links are
http://only. Lamps serve plain http on the LAN, so anhttps://share link is refused ("lamps use http — use the http:// link") rather than guessed at port 443 or 80. - Moved lamps. When a lamp is found at a new address (mDNS re-resolve or
lamps_discover), the new host must report the samedeviceIdon the openGET /apibefore the stored key is sent to it. - Keys. The key is passed to
security -ion stdin, never on its command line.
Uninstall
Remove the server entry from your AI program's settings. The downloaded package stays in npm's
cache (~/.npm/_npx) until you clear it. Optionally, for each profile you used:
rm -rf ~/.plaiiin/lamps-<name> # lamp list and library
security delete-generic-password -s plaiiin-lamp-mcp-<name> # macOS: repeat until none are left
Revoke the AI keys themselves in the app's Share tab.
How releases are built, and how to check one
What npx runs is the npm package plaiiinlight-mcp: a small entry script and one bundled file,
dist/index.js. Nobody reads a bundle, so this repository is arranged to let you check it against
the source instead:
main(this branch) has one commit per release. Each holds that release's source code and what was built from it, in the foldernpm/— exactly the files of the npm package.sourcehas the full commit history of the code, without built files.- The
ciworkflow runs on every release commit. It rebuilds everything from the source in the same commit and fails if the result is not byte-for-byte what was published. - The
releaseworkflow repeats that comparison and only then publishesnpm/to npm, from GitHub's runners, without any stored npm password or token. The package page on npm shows this as provenance: the repository, the commit and the workflow run it came from.
To check a version yourself:
git clone https://github.com/nebeleben/plaiiin-light-mcp && cd plaiiin-light-mcp
git checkout v0.3.0
npm ci && npm run build && git diff --exit-code -- npm # the source builds exactly these files
npm pack plaiiinlight-mcp@0.3.0 && tar -xzf plaiiinlight-mcp-0.3.0.tgz
diff -r package npm && echo "npm delivers exactly this folder"
Versions starting with 0.0.0 on npm are empty placeholders from before the first release (npm
needs a package to exist before it can be published this way). Every other version comes from here.
The version number is shared with the two plugins, so a number may be skipped here when only a plugin was released.
More on building and testing in CONTRIBUTING.md.
Licence
Apache-2.0, see LICENSE.
plaiiinlight-mcpnpm install plaiiinlight-mcp