AI导哈

Pixelorama自动化桥接工具

提供Pixelorama的自动化桥接插件和独立MCP服务器，支持通过命令行和API进行自动化操作。

  • by guojidan
  • GDScript
  • 本地部署
  • 更新于
在 GitHub 查看 guojidan/Pixelorama-mcp

使用说明

Pixelorama MCP

本项目提供 独立 MCP server（stdio） 与 Pixelorama 扩展桥接插件，无需 fork Pixelorama 即可自动化。

运行前提

  • 已安装 Pixelorama（官方 App 即可）
  • Python 3.13.7（建议使用 uv 创建虚拟环境）

使用教程（完整流程）

0) 创建虚拟环境（uv）

cd /Users/dandan/code/tool/Pixelorama-mcp
uv venv --python 3.13.7 .venv
source .venv/bin/activate

1) 构建扩展包

python3 extension/build_extension_zip.py

产物：

extension/dist/PixeloramaMCP.zip

2) 安装扩展包到 Pixelorama

将 zip 放入 Pixelorama 扩展目录：

  • macOS: ~/Library/Application Support/Pixelorama/extensions/
  • 也可在 Pixelorama 的 Extension Manager 中安装 zip

安装后在扩展管理器中启用 Pixelorama MCP Bridge。

3) 启动 Pixelorama

GUI 模式（推荐）：

/Applications/Pixelorama.app/Contents/MacOS/Pixelorama

Headless 模式（自动化/CI）（可选）：

/Applications/Godot.app/Contents/MacOS/Godot --headless --path /path/to/Pixelorama

扩展启用后，Pixelorama 会启动本地 TCP bridge（默认 127.0.0.1:8123）。

4) 启动 MCP Server（stdio）

cd server
../.venv/bin/python -m pixelorama_mcp

可选环境变量：

  • PIXELORAMA_BRIDGE_HOST（默认 127.0.0.1）
  • PIXELORAMA_BRIDGE_PORT（默认 8123）
  • PIXELORAMA_BRIDGE_PORTS（例如 8123,8124，用于端口扫描）
  • PIXELORAMA_BRIDGE_PORT_RANGE（例如 8123-8133）
  • PIXELORAMA_BRIDGE_TOKEN（启用后所有请求需携带 token）

如果启用 token，需要用同一个 token 启动 Pixelorama 与 MCP server。

5) 自动化测试脚本

../.venv/bin/python /Users/dandan/code/tool/Pixelorama-mcp/tests/run_mcp_tests.py

测试覆盖：导入/导出、图层/帧/像素、绘制、选择、动画、Tilemap、效果、笔刷、调色板等。

扩展/边界测试（错误参数、协议与安全校验）：

../.venv/bin/python /Users/dandan/code/tool/Pixelorama-mcp/tests/run_mcp_tests_extra.py

与 Codex 集成

1) 启动 Pixelorama（官方 App）

如果启用 token，必须从终端启动 Pixelorama.app 才能注入环境变量。

PIXELORAMA_BRIDGE_TOKEN=YOUR_TOKEN \
/Applications/Pixelorama.app/Contents/MacOS/Pixelorama

2) 注册 MCP Server 到 Codex

codex mcp add pixelorama \
  --env PIXELORAMA_BRIDGE_HOST=127.0.0.1 \
  --env PIXELORAMA_BRIDGE_PORT=8123 \
  --env PIXELORAMA_BRIDGE_TOKEN=YOUR_TOKEN \
  -- /Users/dandan/code/tool/Pixelorama-mcp/.venv/bin/python -m pixelorama_mcp

完成后在 Codex 里输入 /mcp，确认已连接到 pixelorama。

3) 使用方式

在 Codex 里直接描述需求即可，例如：

  • “新建 32x32 画布，画一个红色圆点并导出 PNG。”
  • “把当前项目导出成 GIF，标签为 walk，方向 forward。”

与 Gemini CLI 集成（0.26.0）

在 ~/.gemini/settings.json 中新增 mcpServers.pixelorama：

{
  "mcpServers": {
    "pixelorama": {
      "command": "/Users/dandan/code/tool/Pixelorama-mcp/.venv/bin/python",
      "args": ["-m", "pixelorama_mcp"],
      "cwd": "/Users/dandan/code/tool/Pixelorama-mcp/server",
      "env": {
        "PYTHONPATH": "/Users/dandan/code/tool/Pixelorama-mcp/server",
        "PIXELORAMA_BRIDGE_HOST": "127.0.0.1",
        "PIXELORAMA_BRIDGE_PORT": "8123"
      }
    }
  }
}

如果启用了 token，需要在 env 里加：

"PIXELORAMA_BRIDGE_TOKEN": "YOUR_TOKEN"

修改后重启 Gemini CLI 即可生效。

协议与更多文档

  • Bridge 协议：docs/bridge-protocol.md
  • 能力清单：docs/capabilities.md
  • 路线图：docs/mcp-roadmap.md
  • 详细步骤：docs/setup.md

相关 MCP