Pencil2D Model Context Protocol (MCP) Server

An open-source Model Context Protocol (MCP) server and automation toolkit that empowers AI agents (Claude Desktop, Google Antigravity, Cursor, Cline, etc.) to programmatically create, inspect, edit, and render traditional 2D hand-drawn animations using Pencil2D.

✨ Features

• ⚡ Zero Heavyweight Runtime Dependencies: Pure Python implementation with standard library + Pillow.
• 🎬 Headless & Pure-Python Dual Rendering: Leverages Pencil2D AppImage CLI or built-in pure-Python Pillow fallback to render animations to MP4 (H.264), animated GIF, or PNG image sequences—even in headless environments without an X server.
• 🎨 Complete Project (.pclx) Support: Read, construct, and modify native .pclx archives, layer structures (Bitmap, Vector, Sound, Camera, Palette), frame timings, and camera transformations.
• ⚡ Batch Frame Operations: Import whole animations from directories or structured lists in a single operation.
• 🔊 Sound & Audio Integration: Embed voiceovers and sound effects (WAV/MP3) directly into sound layers.
• 🎥 Dynamic Camera Controls: Keyframe camera pan (dx, dy), zoom (scale), and rotation angles.
• 🖼️ Spritesheet Generator: Pack animated frames into game-ready spritesheet PNGs with coordinate metadata.
• 🩺 Project Health & Validation: Sanity check .pclx projects for broken links, missing frame gaps, and XML errors.
• 🖥️ Dual Execution Modes: Automated background pipelines or live visual GUI launching (pencil2d_launch_gui).
• 🔌 Standard MCP Compatibility: Speaks JSON-RPC 2.0 over standard I/O (stdio transport).

🛠️ Complete MCP Toolset (14 Tools)

Every tool is exposed as a first-class AI tool over MCP:

🚀 Installation

Option 1: From PyPI

pip install pencil2d-mcp

Option 2: From Source

git clone https://github.com/chriz-3656/pencil2d-mcp.git
cd pencil2d-mcp
pip install -e .

Pencil2D Executable Prerequisite

Download the official Pencil2D Linux AppImage (v0.7.2 or newer) and make it executable:

chmod +x ~/Downloads/pencil2d-linux-amd64-v0.7.2.AppImage

⚙️ Client Configuration

1. Google Antigravity (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "pencil2d": {
      "command": "python3",
      "args": ["-m", "pencil2d_mcp", "serve"],
      "env": {
        "PYTHONPATH": "/home/demo/pencil2d-mcp/src",
        "PENCIL2D_APPIMAGE": "/home/demo/Downloads/pencil2d-linux-amd64-v0.7.2.AppImage",
        "DISPLAY": ":0.0"
      }
    }
  }
}

2. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "pencil2d": {
      "command": "python3",
      "args": ["-m", "pencil2d_mcp", "serve"],
      "env": {
        "PENCIL2D_APPIMAGE": "/path/to/pencil2d-linux-amd64-v0.7.2.AppImage"
      }
    }
  }
}

3. Cursor / Cline / Roo-Code

{
  "mcpServers": {
    "pencil2d": {
      "command": "pencil2d-mcp",
      "args": ["serve"]
    }
  }
}

💻 CLI Usage

# Verify system setup, AppImage detection, and display
pencil2d-mcp check

# Inspect a .pclx project
pencil2d-mcp inspect animation.pclx

# Headlessly export animation to MP4 or GIF (supports AppImage CLI or pure-Python fallback)
pencil2d-mcp export animation.pclx -o output.mp4 --fps 24
pencil2d-mcp export animation.pclx -o preview.gif --width 800 --height 600 --pure-python

# Open project in GUI
pencil2d-mcp gui animation.pclx

# Start the MCP stdio server manually
pencil2d-mcp serve

🧪 Testing

python -m unittest discover tests

📜 License

Distributed under the MIT License. See LICENSE for details.

Maintained with ❤️ by chriz-3656.