pixoo-mcp-server

Seven tools covering the full display pipeline — from quick styled text to full layered scene composition, device control, and initial setup:

The primary tool for text-only display. Covers the 80% case — styled text with quality defaults.

- Named scene themes set background gradient and text palette in one parameter (midnight,ember,claude,ice,neon,forest,mono)
- Style block: gradient palette ramps (ember,ice,neon,fire,lavender,claude,mono), drop shadow, 1px outline for legibility, integer scale multiplier for block-letter weight
- Semantic positioning:x: "center",y: "bottom"— no manual pixel math
- Auto-fit overflow: tries 5×7 → 3×5 → scroll; every fit decision reported inlayout[]
- Returns the rendered frame as an image content block so you see it immediately
- Optional brightness convenience parameter applied before push

Full scene composition with the complete element vocabulary.

- Layered elements rendered back-to-front:text,icon,rect,circle,line,progress,sparkline,bitmap,pixels,image,sprite
- Named icons from the built-in registry (weather, arrows, status, media) or custom SVG path
- Dashboard widgets:progressbar with gradient fill and optional label;sparklinemini chart (line or bar, auto-scaled)
- Animation: named effect presets (float,scroll-left,scroll-right,pulse,blink,twinkle,drift,fade-in,fade-out) or raw keyframe arrays — 1–40 frames, configurable speed
- Per-element opacity andvisibleflag; images at https URLs fetched server-side to a temp file
- Returns a preview image (static: PNG; animated: labeled contact-sheet PNG + GIF saved to disk)

Push any image to the display with control over the downsampling.

- Accepts absolute local paths and https URLs
- Three fit modes:contain(letterbox),cover(crop to fill),fill(stretch)
- Three resize kernels:nearestfor pixel art,lanczos3for photos,mitchellfor a balance
- Returns the exact 64×64 result as an image block — you see what the display received

Device-native scrolling text overlay — persists across channel switches.

- 115 device-rendered font IDs (0–114)
- Up to 20 independent overlay slots (IDs 0–19)
- Configurable scroll direction, speed, and alignment
- Clears withmode: "clear"— overlays survive channel changes until explicitly removed
- Not previewable (device-rendered); for styled previewable text usepixoo_display_text

The orientation tool. Run before authoring any scene to get grounded in 64px craft constraints.

- Six topics:text,scene,dashboard,animation,pixel-art,troubleshooting
- Returns legibility floors, palette discipline, layout zones, animation budgets, and common pitfalls
- Merges live device state (reachable, channel, brightness, screen) into the response
- Pre-fillednextToolSuggestionswith ready-to-use arguments based on current device state

All resource data is also reachable via tools.pixoo_design_briefsurfaces the design guide content per topic;pixoo_control_devicereturns live device state equivalent topixoo://device/status.

- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
- Unified error handling — handlers throw, framework catches, classifies, and formats
- Pluggable auth:none,jwt,oauth
- Swappable storage backends:in-memory,filesystem,Supabase,Cloudflare KV/R2/D1
- Structured logging with optional OpenTelemetry tracing
- STDIO and Streamable HTTP transports

- Requires a Divoom Pixoo LED matrix display on the local network; primary target is the Pixoo-64 (16 and 32 also supported)
- All composition happens in an RGBA canvas pipeline on the host (@cyanheads/pixoo-toolkit) — the device receives final RGB frames, never raw drawing commands
- Styled text engine: gradient palette ramps, drop shadows, outlines, integer scale, semantic alignment — no manual pixel math or bitmap letterforms required
- Push pacing: device commands serialized with a configurable minimum inter-push interval (default 1000ms) to prevent device freezes
- EveryPixooResultchecked —pushed: truemeans the device acknowledged witherror_code: 0, never "I tried"
- Animation capped at 40 frames (device instability beyond this); contact-sheet PNG preview for animations (GIF inconsistent across MCP clients)
- Local transports only —sharpimage processing doesn't run on Cloudflare Workers

- Preview-as-content: render tools return the upscaled (8×, 512px) output as an image content block — the calling model sees exactly what was drawn, before and after push
- Layout transparency: every silent renderer decision (font fallback, truncation, scroll engaged, element clipped) reported inlayout[]so agents can inspect and refine
- Device truth:pushedreflects the device ACK;deviceStatepost-push flags visibility issues (screen off, brightness ≤ 10, wrong channel) as enrichment notices rather than failures
- Graceful degradation: render succeeds and returns the preview even when the device is unreachable — the agent keeps its work

Requirements:A Divoom Pixoo display (Pixoo-64, Pixoo-32, or Pixoo-16) on the same local network as the server. Runpixoo_discover_devicesto find its IP, then setPIXOO_IPin your server configuration.

Add the following to your MCP client configuration file:

{ "mcpServers": { "pixoo-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/pixoo-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info", "PIXOO_IP": "192.168.1.50" } } } }

{ "mcpServers": { "pixoo-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/pixoo-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info", "PIXOO_IP": "192.168.1.50" } } } }

{ "mcpServers": { "pixoo-mcp-server": { "type": "stdio", "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "PIXOO_IP=192.168.1.50", "ghcr.io/cyanheads/pixoo-mcp-server:latest" ] } } }

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 PIXOO_IP=192.168.1.50 bun run start:http # Server listens at http://localhost:3010/mcp

- Bun v1.3.2or higher (or Node.js v24+).
- A Divoom Pixoo LED matrix display on the local network (Pixoo-64, Pixoo-32, or Pixoo-16). Discovery tools and pure-render tools (push: false) work without a configured device.

git clone https://github.com/cyanheads/pixoo-mcp-server.git

cp .env.example .env # edit .env and set PIXOO_IP

See.env.examplefor the full list of optional overrides.

# One-time build bun run rebuild # Run the built server bun run start:stdio # or bun run start:http

bun run devcheck # Lint, format, typecheck, security bun run test # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec

docker build -t pixoo-mcp-server . docker run --rm -e PIXOO_IP=192.168.1.50 -p 3010:3010 pixoo-mcp-server

SeeCLAUDE.md/AGENTS.mdfor development guidelines and architectural rules. The short version:

Blynk's MCP server lets AI coding tools create device templates, manage devices, and read live sensor data on the Blynk IoT platform