pixoo-mcp-server

<div align="center"> <h1>@cyanheads/pixoo-mcp-server</h1> <p><b>Render and push styled pixel art, text, dashboards, and animations to Divoom Pixoo LED displays on your local network via MCP. STDIO or Streamable HTTP.</b> <div>8 Tools • 4 Resources</div> </p> </div> <div align="center">

</div> <div align="center">

</div>

---

Overview

Divoom Pixoo LED matrix displays on the local network, with the Pixoo-64 as the primary target and the 16 and 32 also supported. Render and push styled text, layered scenes, dashboards, animations, and HTML pages, or read and change device state. Runs as a stdio process or a local Streamable HTTP server.

Tools

| Tool | Description | |:---|:---| | pixoo_display_text | Render styled text with themes, gradients, shadows, and auto-fit, static or animated, and push it | | pixoo_compose_scene | Compose layered scenes of text, icons, widgets, shapes, bitmaps, images, and sprites, static or animated | | pixoo_push_image | Resize a local or https image to the LED grid and push it, an animated GIF or WebP as an animation | | pixoo_render_html | Render an HTML page (CSS, SVG, Canvas, WebGL) in a headless browser at the panel size, still or animated frame by frame on a virtual clock, and push it | | pixoo_overlay_text | Set or clear a device-rendered scrolling text overlay | | pixoo_control_device | Read or change brightness, screen state, channel, or clock face | | pixoo_discover_devices | Find Pixoo devices and their LAN IPs through Divoom's cloud discovery | | pixoo_design_brief | Craft guidance for a design topic, with live device state and pre-filled next calls |

Resources

| Resource | Description | |:---|:---| | pixoo://device/status | Live device snapshot: reachability, channel, brightness, screen state, display size | | pixoo://reference/themes | Theme and palette registry | | pixoo://reference/icons | Built-in icon names by category | | pixoo://reference/design-guide | Long-form craft guide for the 64px display |

Tools cover the same ground for tool-only clients: pixoo_control_device reads the live device state, and pixoo_design_brief returns craft guidance, theme names, and icon names.

Capability reference

pixoo_display_text _tool

• text as a string or an array of lines; theme (midnight, ember, claude, ice, neon, forest, mono) sets the background and default palette. style takes a palette ramp (ember, ice, neon, fire, lavender, claude, mono) or a custom { from, to }, plus shadow, outline, and scale 1–8; position is semantic or in pixels, and align lines up multi-line text
• font: standard (5×7) and compact (3×5) draw printable ASCII plus ° ← ↑ → ↓ ▲ ▼ ♥ · …, and any other character (€, ’, a newline inside one string) as ?, named with its code point and line index in the response notice; numerals is an 11×18 digit face for clocks and readouts that draws 0–9, space, and : . - + / % ° ?, and text holding any other character fails validation, naming those characters
• layout[] reports every fit decision as an action (shrunk-to-compact when the text fits only in the compact font, scrolling when the returned frames scroll, none otherwise), the font used, and whether each line's box fits on the panel; a single line too wide for the panel starts at x 0, cut at the right edge when it does not scroll. Single-line text falls back from the standard to the compact font unless font is set — never to numerals — and text still too wide only scrolls under effect: "auto" or "scroll"
• effect: scroll makes one pass in up to 40 frames, auto scrolls only on overflow, and float and pulse loop over 20 frames; frames reports the count, and the animation pushes as one device animation

---

pixoo_compose_scene _tool

• Up to 50 elements drawn back-to-front: text (in the same three fonts as pixoo_display_text), icon, rect, circle, line, progress, sparkline, bitmap, pixels, image (absolute path or https URL, with the same finish as pixoo_push_image), sprite (absolute path). The background is a solid color, a v / h / r gradient, or a theme
• Every element takes opacity (each pixel lands at its own alpha × opacity, so soft edges fade evenly) and blend: normal, add (glows and light beams), screen, or multiply. line and outline circle take strokeWidth and antialias, and a rect border takes strokeWidth, growing inward; either field on a shape that draws no stroke fails validation, naming it
• Returns layout[]: each element's placed box — for a wide or anti-aliased stroke, every pixel it draws — and whether it fits on the panel. Elements are placed as given and never refit, so action is always none. An absolute output path saves the first frame as a PNG in place of the PIXOO_OUTPUT_DIR auto-save. Typed failures: asset_not_found, invalid_image (an image or sprite that was read but does not decode), invalid_color, unknown_icon, invalid_output_path
• Animation through per-element effect presets (float, scroll-left, scroll-right, pulse, blink, twinkle, drift, fade-in, fade-out) or raw animate keyframes over dx, dy, opacity (numbers or numeric strings), visible (true/false), and color (interpolated through RGB on any element with a color), each track holding at least one keyframe; frames 1–800, speed 10–2000 ms per frame (default 150). Past 40 frames the scene plays as one GIF the device downloads from this host, with speed rounded to 10 ms. An element takes effect or animate, not both. An effect's amplitude sets the movement of float, scroll-*, and drift, and the 0–1 depth of the pulse and twinkle opacity dip

---

pixoo_push_image _tool

• source is an absolute local path or an https URL, with downloads capped at 10 MB; fit is contain (default), cover, or fill, and kernel is nearest (default, for pixel art), lanczos3 (photos), or mitchell
• A source that decodes as an animated GIF or WebP, whatever its file name, pushes as an animation of up to maxFrames frames (1–800, default 40), sampled evenly from a longer source; past 40 frames it plays as one GIF the device downloads from this host. It plays at the source's total duration over the pushed frame count (150 ms when the source records no delays), or at speed (10–2000 ms per frame); frames, sourceFrames, and speed report what was pushed
• finish reduces the image to a palette before the push: exactly one of colors (2–256, built from the image) or palette (1–256 hex or named colors), plus dither (none, bayer4, floyd-steinberg). Transparent pixels stay unlit, and an animation's colors palette is shared by every frame
• An unreadable path or URL fails as asset_not_found, a source that is read but does not decode (a text file, an HTML page, a truncated download) fails as invalid_image, and an unresolvable finish palette entry fails as invalid_color; the preview is the exact frame the device receives, or a grid of an animation's frames

---

pixoo_render_html _tool

• html is a full document or a body fragment, up to 500,000 characters, laid out in a square viewport one CSS pixel per LED. The page is the panel: body has no margin, scrollbars are hidden, and a page that paints no background renders on black (unlit). Its own CSS overrides each

• frames 1–800 (default 1), speed 10–2000 ms per frame (default 150). Each frame advances a virtual clock by speed: window.render(t, frame), when the page defines it, runs before each capture with t = frame / frames, so periodic motion loops seamlessly; requestAnimationFrame, setTimeout / setInterval (4 ms floor for nested and repeating timers), Date (starting at the real time), and performance.now() (0 at load) follow the same clock, and CSS animations are paused and seeked to it, so every frame is deterministic. requestIdleCallback and iframes keep real time. Past 40 frames the page plays as one GIF the device downloads from this host, as on pixoo_compose_scene

• sampling: native (default) or supersample, which renders at 8× and area-averages into each LED, smoothing transforms, text, SVG, and canvas. Chromium snaps a plain box's edges to whole CSS pixels before scaling, so a box at left: 0.5px still lands on one LED; move it with transform for sub-pixel motion. finish takes the same palette reduction as pixoo_push_image, applied before the preview

• Nothing loads from the network and workers are blocked. pageErrors returns the page's uncaught errors, console.error output, and blocked URLs (a blocked navigation as Blocked navigation: <url>): the first 20, each cut to 500 characters. A window.render that throws or rejects fails as page_error, naming the frame; with no browser found, the call fails as browser_unavailable with install steps (see Prerequisites); render_timeout and render_crashed cover a render past 30 s and a crashed browser or page. PIXOO_HTML_ENABLED=false removes the tool

• Every page gets a pixoo global before its own scripts run, for the crisp bitmap text, palettes, and icons that browser anti-aliasing would smear across LEDs:

  • pixoo.context() is the 2D context of a transparent panel-size canvas fixed over the page.
  • pixoo.text(ctx, text, x, y, { font, color, palette, scale, shadow, outline }) draws pixoo_display_text's fonts.
  • pixoo.icon(ctx, name, x, y, { w, h, color, palette }) draws a registry icon.
  • pixoo.palettes holds the 7 palettes, and pixoo.size is the panel size.

  Text and icons drawn this way match pixoo_compose_scene pixel for pixel in both sampling modes. An unknown palette, icon, or color throws naming it:

  <script>
    const ctx = pixoo.context();
    pixoo.text(ctx, 'HELLO', 'center', 4, { palette: 'ember', scale: 2, shadow: true });
    pixoo.icon(ctx, 'check-circle', 50, 50, { color: