# io.github.cyanheads/pixoo-mcp-server (npm · @cyanheads/pixoo-mcp-server)

Render and push styled pixel art, text, dashboards, and animations to Divoom Pixoo LED displays.

- Trust score: 67/100 (medium)
- Change this week: +52
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-07

## Components

- npm · `@cyanheads/pixoo-mcp-server`: 67/100 (this document), [markdown](https://verifymcp.io/servers/cyanheads-pixoo-mcp-server/cyanheads-pixoo-mcp-server.md), [page](https://verifymcp.io/servers/cyanheads-pixoo-mcp-server/cyanheads-pixoo-mcp-server)

## Channel facts

- Registry: `npm`
- Package: `@cyanheads/pixoo-mcp-server`
- Version: `1.0.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-07.

- **Supply Chain Security**: 90/100
  - No malware found by supply-chain analysis.
  - CVE check failed: a known high-severity CVE affects sharp 0.34.5, reached via @cyanheads/pixoo-toolkit > sharp. A fixed version is available.
  - No install/post-install scripts declared.
  - 41 of 186 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (Apache-2.0).
  - Actively maintained (last published 55 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 81/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 1590 tokens (~144/item across 11 items; 7 tools + 4 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add cyanheads-pixoo-mcp-server -- npx -y @cyanheads/pixoo-mcp-server
```

### Codex

```bash
codex mcp add cyanheads-pixoo-mcp-server -- npx -y @cyanheads/pixoo-mcp-server
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cyanheads-pixoo-mcp-server": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@cyanheads/pixoo-mcp-server"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add cyanheads-pixoo-mcp-server --command npx --arg -y --arg @cyanheads/pixoo-mcp-server
```

### Hermes

```yaml
mcp_servers:
  cyanheads-pixoo-mcp-server:
    command: "npx"
    args: ["-y", "@cyanheads/pixoo-mcp-server"]
```

### Other

```json
{
  "mcpServers": {
    "cyanheads-pixoo-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/pixoo-mcp-server"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-07 (score 67, +3)

- [functional] Dependency health: partial → 0.91

### 2026-08-06 (score 64, +31)

- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] Schema quality: unverified → 100
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Tool coverage: unverified → 100
- [functional] First check of Tool coverage: 100
- [functional] First check of Tool coverage: 100
- [functional] First check of Schema quality: fail
- [functional] First check of Schema quality: excellent
- [functional] First check of Schema quality: fail

### 2026-08-05 (score 33, 0)

- [security improvement] CVE-2026-69207 no longer affects this package

### 2026-08-04 (score 33, 0)

- [security regression] CVE-2026-69207 affects this package: high

### 2026-08-02 (score 33, +28)

- [security regression] GHSA-f88m-g3jw-g9cj affects this package: high
- [security regression] Provenance: unverified → fail
- [security regression] Known CVEs: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] License: unverified → pass
- [functional improvement] Maintenance: unverified → pass
- [functional] Tool coverage: Tool coverage not yet verified: we do not have a sandbox capture of the tool definitions this version of the package serves yet.
- [functional] Capabilities: Protocol version not yet verified: we do not have a sandbox capture of the MCP handshake this version of the package performs yet.
- [functional] Schema quality: Schema quality not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional] Licence: Apache-2.0

### 2026-08-01 (score 5, −10)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 15, −10)

- [security regression] Provenance: unverified → fail
- [security regression] Malware scan: pass → unverified
- [security improvement] Install scripts: unverified → pass
- [functional regression] Dependency health: partial → unverified
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] License: unverified → pass
- [functional] Tool coverage: Tool coverage not yet verified: our sandbox run of this package did not complete, so we have no tool definitions to assess.
- [functional] Schema quality: Schema quality not yet verified: our sandbox run of this package did not complete, so we have no schema to assess.
- [functional] Licence: Apache-2.0

### 2026-07-29 (score 25, +1)

- [functional improvement] Dependency health: unverified → partial
- [functional] Tool coverage: Tool coverage not yet verified: we do not have a sandbox capture of the tool definitions this version of the package serves yet.
- [functional] Schema quality: Schema quality not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.

## MCP tools (7)

### `pixoo_display_text` (~278 tokens)

Render styled text (theme, gradient, shadow, outline, auto-fit) onto the Pixoo display and push it. Returns the rendered frame as an image content block for immediate inspection. The primary tool for text-only display — for layers, icons, widgets, or animations use pixoo_compose_scene. Run pixoo_design_brief with topic "text" first for palette and legibility guidance.

Input parameters:

- `align` (string): Multi-line text alignment (default: center).
- `background`: Background color or gradient. Overrides theme background when set.
- `brightness` (integer): Set device brightness before push (0–100). Failure is a warning, not an error.
- `effect` (string): Animation effect. auto = scroll only when text overflows. Produces a multi-frame result.
- `font` (string): Font variant: standard (5×7) or compact (3×5). Auto-fit will choose if omitted.
- `position` (object): Text position on the display.
- `push` (boolean): Push the rendered frame to the device (default: true).
- `style` (object): Text style: palette, shadow, outline, scale.
- `text` (required): Text to display. String or array of lines.
- `theme` (string): Named scene theme — sets background gradient and default text palette.

Output parameters:

- `deviceState` (object): Device state after the push. Absent when push: false.
- `layout` (array): Layout report: every fit decision the renderer made.
- `notice` (string): Warning or informational message about the render or push.
- `outputFiles` (array): Absolute paths to saved PNG preview files. Present only when PIXOO_OUTPUT_DIR is configured.
- `previewData` (string): Base64-encoded PNG preview of the rendered frame (8× upscaled, 512px).
- `previewMimeType` (string): MIME type of the preview image.
- `pushed` (boolean): True when the device acknowledged the push.

### `pixoo_compose_scene` (~221 tokens)

Compose a full scene: layered elements (text, icons, widgets, shapes, bitmaps, images, sprites) with per-element effects and keyframes, static or animated. Returns the rendered scene as an image content block for immediate inspection. Elements render back-to-front in array order. For text-only display use pixoo_display_text; run pixoo_design_brief with topic "scene" or "dashboard" for layout and palette guidance.

Input parameters:

- `background` (required): Scene background: solid color, gradient, or named theme.
- `elements` (array, required): Scene elements rendered back-to-front. Up to 50 elements.
- `frames` (integer): Number of animation frames (1–40, default: 1). 20 frames at 150ms ≈ 3s loop.
- `output` (string): Explicit output file path for saving (overrides PIXOO_OUTPUT_DIR).
- `push` (boolean): Push to device (default: true).
- `speed` (integer): Milliseconds per frame for animations (default: 150ms).

Output parameters:

- `deviceState` (object): Device state after the push. Absent when push: false.
- `frames` (number): Number of frames in the rendered output (1 for static, 2–40 for animations).
- `layout` (array): Layout report for each element.
- `notice` (string): Warning or informational notice about the render or push.
- `outputFiles` (array): Absolute paths to saved output files (PNG for static, GIF for animations). Present only when PIXOO_OUTPUT_DIR is configured or output is set.
- `previewData` (string): Base64-encoded PNG preview of the rendered scene (8× upscaled, 512px). For animations: the middle frame.
- `previewMimeType` (string): MIME type of the preview image.
- `pushed` (boolean): True when the device acknowledged the push. False when push: false or push failed.

### `pixoo_push_image` (~168 tokens)

Load an image (absolute local path or https URL), resize it to fit the LED grid, and optionally push it to the display. Returns the downsampled result as an image content block so you see exactly what the display received. Nearest-neighbor kernel preserves pixel art; use lanczos3 or mitchell for photos.

Input parameters:

- `fit` (string): Resize fit mode: contain (letterbox), cover (crop to fill), fill (stretch).
- `kernel` (string): Resize kernel: nearest for pixel art, lanczos3 for photos, mitchell for a balance.
- `push` (boolean): Push the resized image to the device (default: true).
- `source` (string, required): Absolute local file path or https (not http) URL of the image to display.

Output parameters:

- `deviceState` (object): Device state after the push. Absent when push: false.
- `notice` (string): Warning or informational message.
- `outputFiles` (array): Absolute paths to saved PNG preview files. Present only when PIXOO_OUTPUT_DIR is configured.
- `previewData` (string): Base64-encoded PNG preview of the downsampled 64×64 result (8× upscaled, 512px).
- `previewMimeType` (string): MIME type of the preview image.
- `pushed` (boolean): True when the device acknowledged the push.

### `pixoo_overlay_text` (~320 tokens)

Set or clear a device-native scrolling text overlay. Use mode "set" to add or update an overlay on a slot (0–19); use mode "clear" to remove it. Overlays use device-rendered fonts (115 font IDs, 0–114) and persist across channel switches until explicitly cleared with mode "clear". Not previewable — rendering happens on-device. Best for persistent tickers over pushed scenes; for styled, previewable text use pixoo_display_text instead.

Input parameters:

- `align` (string): Text alignment (default: left).
- `color` (string): Text color as CSS hex color (default: white).
- `direction` (string): Scroll direction (default: left).
- `font` (integer): Device font ID (0–114). 0 = default, 18 = arrows, 20 = °C/°F. Device-rendered; no preview.
- `id` (integer, required): Overlay slot ID (0–19). Each ID is an independent overlay layer.
- `mode` (string, required): set = add/update overlay; clear = remove it.
- `speed` (integer): Scroll speed (0–100, device units; default: 50).
- `text` (string): Text to display (required for mode=set).
- `width` (integer): Text region width in pixels (optional; defaults to display width).
- `x` (integer): X start position on display (default: 0).
- `y` (integer): Y start position on display (default: 0).

Output parameters:

- `acknowledged` (boolean): True when the device confirmed the overlay command (error_code: 0).
- `id` (number): The overlay slot ID (0–19) that was operated on.
- `mode` (string): Operation performed: "set" (overlay added/updated) or "clear" (overlay removed).

### `pixoo_control_device` (~138 tokens)

Read or change device state: brightness (0–100), screen on/off, channel, or clock face. Call with no params to read current state only. Supply any params to apply changes before reading back state. Use pixoo_discover_devices first if PIXOO_IP is not yet configured.

Input parameters:

- `brightness` (integer): Set display brightness (0–100).
- `channel` (string): Switch to a channel: faces, cloud, visualizer, or custom.
- `clockFaceId` (integer): Select a clock face by ID (channel must be faces).
- `screen` (string): Turn the display screen on or off.

Output parameters:

- `applied` (array): Settings successfully applied in this call (e.g. "brightness:80", "screen:on"). Empty when called with no params or all changes failed. A requested setting that failed is absent here and reported in…
- `brightness` (number): Current brightness level (0–100). Absent when device is unreachable.
- `channel` (string): Current channel name (faces, cloud, visualizer, or custom). Absent when device is unreachable.
- `clockId` (number): Current clock face ID (faces channel only). Absent on other channels or when device is unreachable.
- `reachable` (boolean): True if device responded to the status read.
- `screenOn` (boolean): True if the screen is on. Absent when device is unreachable.

### `pixoo_discover_devices` (~92 tokens)

Find Pixoo devices on the local network via Divoom's cloud discovery endpoint (requires internet — queries app.divoom-gz.com). Run once during initial setup to find device IPs; set PIXOO_IP in server configuration to enable all other tools. For ongoing device control use pixoo_control_device.

Input parameters:

- `timeoutMs` (integer): Discovery timeout in milliseconds (default: 5000ms).

Output parameters:

- `configuredIp` (string): Currently configured PIXOO_IP value (absent if not set).
- `configuredIpFound` (boolean): True if PIXOO_IP matches a discovered device; false signals an IP mismatch. Absent when PIXOO_IP is not set.
- `devices` (array): Discovered Pixoo devices on the local network.
- `notice` (string): Recovery hint when no devices found or IP mismatch.

### `pixoo_design_brief` (~121 tokens)

Return craft guidance and live device context for a design topic. Covers legibility rules, palette discipline, layout zones, animation budget, and pre-filled next-tool suggestions based on current device state. The orientation tool to run before authoring a scene, dashboard, or animation — or when troubleshooting display issues.

Input parameters:

- `topic` (string, required): Design topic: text (styled text guidance), scene (composition + layout zones), dashboard (widgets + metrics), animation (motion budget + effects), pixel-art (bitmap + sprite guidance), troubleshootin…

Output parameters:

- `availableThemes` (array): Available named scene themes (e.g. "midnight", "ember"). Use in background.theme or pixoo_display_text theme param.
- `craftGuidance` (string): Markdown-formatted craft rules: legibility floors, palette discipline, layout zones, and technique guidance specific to the topic.
- `deviceContext` (object): Live device state snapshot at the time of the request.
- `iconCategories` (object): Built-in icon names grouped by category (weather, arrows, status, media). Use names in pixoo_compose_scene icon elements.
- `nextToolSuggestions` (array): Suggested next steps based on topic and device state.
- `topic` (string): The topic that was requested.

## Diagnostics

Captured diagnostic sections: Provenance, Vulnerabilities, Dependencies. The full working is on the page: https://verifymcp.io/servers/cyanheads-pixoo-mcp-server/cyanheads-pixoo-mcp-server#diagnostics

## Score history

- 2026-08-07: 67
- 2026-08-06: 64
- 2026-08-05: 33
- 2026-08-04: 33
- 2026-08-03: 33
- 2026-08-02: 33
- 2026-08-01: 5
- 2026-07-31: 15
- 2026-07-29: 25
- 2026-07-28: 24
- 2026-07-27: 24

## Links

- npm package: https://www.npmjs.com/package/@cyanheads/pixoo-mcp-server
- Socket report: https://socket.dev/npm/package/@cyanheads/pixoo-mcp-server
- Repository: https://github.com/cyanheads/pixoo-mcp-server
- Changelog RSS feed: https://verifymcp.io/servers/cyanheads-pixoo-mcp-server/cyanheads-pixoo-mcp-server.xml
- Changelog JSON feed: https://verifymcp.io/servers/cyanheads-pixoo-mcp-server/cyanheads-pixoo-mcp-server.json
- HTML version of this page: https://verifymcp.io/servers/cyanheads-pixoo-mcp-server/cyanheads-pixoo-mcp-server