Pixoo MCP Server

@cyanheads/pixoo-mcp-server

Your Pixoo, programmable via LLM

Compose and push pixel art, animations, and text to Divoom Pixoo LED matrices via MCP.

4 Tools · STDIO & Streamable HTTP

______________________________________________________________________

🛠️ 工具概述

该服务器提供4个工具，用于编写视觉内容并将其推送到Pixoo显示器：

两者 pixoo_compose 和 pixoo_push_image 自动将设备切换到 custom 在推动之前。

🚀 入门指南

MCP客户端设置

将以下内容添加到MCP客户端配置文件中（例如。， claude_desktop_config.json).客户端有不同的配置服务器的方法，因此请参阅客户端的文档以了解详细信息。

一定要设置 PIXOO_IP 到本地网络上Pixoo设备的IP地址。

克劳德代码

claude mcp add pixoo-mcp-server -e PIXOO_IP=YOUR_DEVICE_IP -- bunx @cyanheads/pixoo-mcp-server@latest

使用丁腈橡胶（Bun）

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

流式HTTP配置

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010

先决条件

• Bun v1.2.0+
• 同一本地网络上的Divoom Pixoo设备

开发环境设置

1. 克隆存储库：

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

1. 安装依赖项：

bun install

1. 配置环境：

cp .env.example .env
# Edit .env and set PIXOO_IP to your device's IP address

1. 运行：

bun run dev:stdio    # Development (hot reload)
bun run devcheck     # Lint, format, typecheck, audit
bun run rebuild && bun run start:stdio  # Production

✨ 特性

• 完整组合管道：图层文本、图像、精灵、形状、位图和单个像素——静态或动画，最多40帧。
• 动画关键帧：每元素属性动画，数字采用线性插值，十六进制值采用颜色提醒，布尔值采用捕捉过渡。
• Sprite支持：通过以下方式加载带有自动下采样和可选主体/深色覆盖的角色表 @cyanheads/pixoo-toolkit.
• 位图字体渲染：内置 standard （5x7）和 compact （3x5）像素字体，适用于任何显示尺寸的清晰文本。
• 自动保存预览：可选择将PNG预览（静态）或动画GIF保存到可配置的输出目录。
• 原生文本叠加：通过设备固件硬件渲染的滚动文本——通过可配置的字体、对齐方式和速度在通道开关上保持不变。

建立在 mcp-ts-template --声明性工具定义、结构化错误处理、可插拔身份验证（JWT/OAuth）、可交换存储后端、OpenTetry可观察性和类型化DI。

⚙️ 配置

关键环境变量：

🎨 工具详细信息

pixoo_compose

主要工具。从分层元素组成场景并推送到设备。元素被拉回到前面。

{
  "background": "black",
  "elements": [
    { "type": "rect", "x": 0, "y": 0, "w": 64, "h": 20, "color": "#1a1a2e" },
    {
      "type": "text",
      "text": "Hello!",
      "x": 0,
      "y": 6,
      "color": "white",
      "font": "standard",
      "centered": true
    },
    {
      "type": "bitmap",
      "x": 28,
      "y": 40,
      "scale": 2,
      "palette": ["", "#ff4488", "#cc2266"],
      "data": ["0120210", "1111111", "1111111", "0111110", "0011100", "0001000"]
    }
  ]
}

元素类型： text, image, sprite, rect, circle, line, bitmap, pixels

动画： 集 frames >1并添加 animate 元素的关键帧：

{
  "frames": 10,
  "speed": 150,
  "elements": [
    {
      "type": "text",
      "text": "Hello",
      "x": 0,
      "y": 2,
      "color": "#ffffff",
      "centered": true,
      "animate": {
        "color": [
          [0, "#ffffff"],
          [5, "#ff8800"],
          [9, "#ffffff"]
        ]
      }
    }
  ]
}

输出选项： 集 output 保存预览PNG（静态）或GIF（动画）的绝对路径。集 push: false 跳过设备推送，只保存预览。

看 docs/pixoo-mcp-server.md 获取完整的元素和动画文档。

pixoo_push_image

加载和推送单个图像文件的快捷方式。支持PNG、JPEG、WebP、GIF、AVIF、TIFF和SVG。

{ "path": "/path/to/image.png", "fit": "contain", "kernel": "nearest" }

pixoo_text

本机设备滚动文本与硬件渲染。叠加渲染在当前显示内容之上，并在频道切换时持续存在。

{ "text": "Hello World", "color": "#00ff00", "speed": 50, "direction": "left" }

使用不同的ID（0-19）来堆叠多个叠加。集 clear: true 以移除覆盖层。

pixoo_control

读取或更改设备设置。无参数调用以读取当前配置。

{ "brightness": 75, "channel": "custom" }

⚠️ 设备问答

• 建议约1推/秒 --快速按压约300次后，设备可能会冻结
• 频道必须 custom 显示推送内容-- compose 和 push_image 自动开关
• 文本叠加持续存在 跨通道开关——使用 clear: true 移除
• 最多约40个动画帧 为了稳定性
• ~5s“加载..”叠加 当新动画开始时
• GIF ID重置 每次推送之前——由工具包自动处理

📚 参考文献

• 输出示例 --由合成工具生成的示例PNG和动画GIF
• API部门文档
• @cyanheads/pixoo工具包 --渲染图元与设备通信
• mcp-ts模板 --服务器基础
• 设备字体列表

贡献

欢迎发布问题和PR。请快跑 bun run devcheck && bun test 在提交之前。

许可证

Apache 2.0