This MCP server lets AI agents programmatically create, inspect, edit, validate, and render Pencil2D .pclx animation projects.
Inspect projects for resolution, FPS, layers, keyframe counts, and palette.
Create new projects and add/remove bitmap, vector, sound, and camera layers.
Insert or replace individual frames and batch-import frames from lists or directories.
Embed audio clips and keyframe camera pan, zoom, and rotation.
Add or update palette color swatches.
Generate spritesheets and extract frame PNGs.
Validate project integrity, including XML, assets, and frame continuity.
Export animations to MP4, animated GIF, or PNG sequences, with optional pure-Python fallback.
Launch projects in the Pencil2D GUI for interactive editing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Pencil2D Model Context Protocol (MCP) Server make a 1920x1080 24fps project named bounce.pclx"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An open-source Model Context Protocol (MCP) server and procedural 2D animation toolkit that empowers AI agents (Google Antigravity, Claude Desktop, Cursor, Cline, Roo-Code, etc.) to programmatically author, inspect, edit, and render broadcast-grade traditional 2D hand-drawn animations using Pencil2D.
🏃 Articulated 2-Bone Inverse Kinematics (IK): Analytic trigonometry ensures exact bone lengths ($L_1, L_2$) for elbows and knees with zero popping, stretching, or distortion.
🚶 Grounded Bipedal Locomotion Engine: True stance foot ground-locking (zero sliding/ice-skating), swing knee lift arcs, double-frequency pelvic vertical bouncing, dynamic torso lean, and natural arm counter-swings.
⚡ Continuous Pose Interpolator: Cubic Hermite ($C^1$) smoothstep blending across all 15 joints, completely eliminating teleporting and instantaneous joint snaps.
💥 Sakuga Anime Combat Engine: Curved velocity motion smear wedges, inverted monochrome Sakuga impact frames, contact hit sparks, speed lines, and camera shake with damped harmonic decay.
🎨 5 Stylized Procedural Renderers: Built-in production generators for Stickman (Martial Arts), Anime (Cel Shading & Hair Volumes), Pencil Sketch (Multi-Pass Graphite Hatching), Studio Ghibli (Rolling Meadow Hills & Painterly Clouds), and Doodle (Marker Wobble & Rubber-Hose Physics).
👁️ Visual Inspection & Feedback (pencil2d_look): Contact sheet filmstrip generator with customizable frame sampling and onion skinning so AI agents verify visual quality without a graphical desktop.
🎬 Headless & Pure-Python Dual Rendering: Leverages official 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 Linux server 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.
🔊 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.
🔌 Standard MCP Compatibility: Speaks JSON-RPC 2.0 over standard I/O (stdio transport).
Related MCP server: rev2d
Every tool is exposed as a first-class AI tool over MCP:
Tool Name | Parameters | Description |
|
| Visually inspect animation via multi-frame contact sheet filmstrip (with frame numbers and onion skinning) or single frame so the AI verifies its work. |
|
| Generate complete stylized animations using authentic artistic presets, squash & stretch physics, and curved lines of action. |
|
| Retrieve craft knowledge guides on 2D animation principles, timing charts, squash & stretch volume preservation, and style recipes. |
|
| Inspect a |
|
| Create a fresh, valid |
|
| Insert or replace an animation frame in a bitmap layer using an image file or base64 data. |
|
| Batch import multiple animation frames from a folder or list in a single call with auto-layer creation. |
|
| Add a new layer to the project timeline. |
|
| Delete a layer and its keyframes from the project. |
|
| Embed an audio track/clip (WAV/MP3) into a sound layer at a specific keyframe. |
|
| Keyframe camera pan, zoom, and rotation angle at any frame. |
|
| Add or update a color swatch in the project palette. |
|
| Pack animated frames into a sprite sheet with coordinate grid metadata. |
|
| Deep project integrity test checking XML syntax, asset references, and frame continuity. |
|
| Unpack all PNG frames from a |
|
| Headlessly render an animation project to video (MP4), animated GIF, or PNG sequence (via AppImage CLI or pure-Python fallback). |
|
| Open the project in the visual Pencil2D GUI for interactive editing. |
[ Head ]
|
( Neck )
/ | \
[L_Shoulder] (MidSpine) [R_Shoulder]
| | |
(L_Elbow)* [ Pelvis ] (R_Elbow)*
| / \ |
[L_Hand] [L_Hip] [R_Hip] [R_Hand]
| |
(L_Knee)* (R_Knee)*
| |
[L_Foot] [R_Foot]
(*) Solved continuously via analytic 2-Bone Inverse Kinematicssolve_2bone_ik(root, target, l1, l2, bend_positive):
Solves triangle angles via Law of Cosines with reach clamping:
$$\cos(\alpha) = \frac{L_1^2 + d^2 - L_2^2}{2 L_1 d}$$
generate_locomotion_pose(x, ground_y, phase, facing, speed):
Generates fully articulated walk, jog, and sprint cycles with true foot ground-locking and pelvic bob.
blend_stickman_poses(pose_a, pose_b, t):
Cubic Hermite smoothstep blending ($s(t) = 3t^2 - 2t^3$) across all joints, ensuring zero teleport jumps.
pip install pencil2d-mcpgit clone https://github.com/chriz-3656/pencil2d-mcp.git
cd pencil2d-mcp
pip install -e .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~/.gemini/config/mcp_config.json){
"mcpServers": {
"pencil2d": {
"command": "python3",
"args": ["-m", "pencil2d_mcp", "serve"],
"env": {
"PYTHONPATH": "/path/to/pencil2d-mcp/src",
"PENCIL2D_APPIMAGE": "/path/to/pencil2d-linux-amd64-v0.7.2.AppImage"
}
}
}
}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"
}
}
}
}.cursor/mcp.json){
"mcpServers": {
"pencil2d": {
"command": "python3",
"args": ["-m", "pencil2d_mcp", "serve"]
}
}
}# Verify system setup, AppImage detection, and display
pencil2d-mcp check
# Inspect a .pclx project
pencil2d-mcp inspect animation.pclx
# Inspect animation filmstrip visually
pencil2d-mcp look animation.pclx -f 1,5,10,15,20 -o preview_strip.png --onion-skin
# Procedurally generate a stylized animation
pencil2d-mcp generate my_walk.pclx --style stickman --action walk --frames 24 --fps 24
# Read craft guide
pencil2d-mcp guide animation
pencil2d-mcp guide styles
pencil2d-mcp guide drawing_techniques
# 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 serveRun the full unit test suite (23 unit tests):
PYTHONPATH=src python3 -m unittest discover tests"This is my first time building an MCP server as a 20-year-old solo developer! If you encounter any bugs, issues, or have feedback, please reach out directly at chrizmonsaji@proton.me or open an issue on GitHub. Every piece of feedback helps!"
Distributed under the MIT License. See LICENSE for details.
Maintained with ❤️ by chriz-3656 • Contact: chrizmonsaji@proton.me.
Attach a sound clip (WAV/MP3) to a sound layer at a specific keyframe in the animation.
Inputs: audio_path (required), project_path (required), frame, layer_name.
Add or replace a keyframe image in a Pencil2D project bitmap layer.
Inputs: frame (required), project_path (required), image_path, layer_name, +3 more.
Batch insert multiple animation keyframes into a project from a list or directory in a single operation.
Inputs: project_path (required), step, frames, layer_name, +3 more.
Add a new layer (bitmap, vector, sound, or camera) to a Pencil2D project.
Inputs: name (required), project_path (required), visible, layer_type.
Create a new blank Pencil2D project (.pclx) with specified canvas resolution, FPS, and layers.
Inputs: project_path (required), fps, width, height, +1 more.
Pack animation frames from a Pencil2D project into a single spritesheet image with grid metadata.
Inputs: output_image (required), project_path (required), columns, layer_name.
Render a Pencil2D animation project to video (MP4), animated GIF, or image sequence using the Pencil2D AppImage CLI.
Inputs: output_path (required), project_path (required), fps, width, +7 more.
Extract all frame PNG images from a .pclx file into a target directory.
Inputs: output_dir (required), project_path (required).
Inspect a Pencil2D project (.pclx file), returning canvas resolution, FPS, keyframe counts, layers, and palette.
Inputs: project_path (required).
Open a project (or a new workspace) inside the Pencil2D GUI for visual animation editing.
Inputs: project_path.
Add or update a color swatch in the Pencil2D project palette.
Inputs: red (required), blue (required), green (required), color_name (required), +2 more.
Remove a layer from a Pencil2D project by name or ID.
Inputs: project_path (required), layer_name_or_id (required).
Configure camera keyframe positioning, panning (dx, dy), zooming (scale), and rotation angle.
Inputs: project_path (required), dx, dy, frame, +2 more.
Perform deep sanity and health validation on a Pencil2D project, verifying frame continuity, XML integrity, and asset health.
Inputs: project_path (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 14 tools
Most tools target clearly distinct operations (export, inspect, validate, create, layer/audio/camera edits). The closest overlap is pencil2d_add_frame vs pencil2d_add_frames_batch, but descriptions distinguish single keyframe replace from bulk insert.
Every tool uses the pencil2d_ prefix followed by a snake_case verb_noun pattern (add_frame, remove_layer, set_camera, manage_palette). The convention is uniform throughout all 14 tools.
14 tools is well within the ideal 3-15 range and each maps to a concrete animation workflow step (create, edit, inspect, export, launch). No redundant or filler tools.
Core lifecycle is covered: create, inspect, validate, add frames/layers/audio, and export to multiple formats. Minor gaps exist (no remove/delete frame or update/rename layer aside from removing, no palette removal), but agents can work around them.
Create AI animations and export transparent sprite sheets, alpha video, frames, and game assets.
Video production studio for AI agents: AI media, motion graphics as code, timeline and export.
AI video editor your agent can drive: plan scenes, edit a multi-track timeline, and render MP4s.
Creator MCP is the hosted LottieFiles animation engine for AI agents. Your agent builds real motion with layers, shapes and keyframes, then exports MP4, WebM, Lottie or dotLottie. Use it for logo reveals, product promos, social clips and UI animations. You can import SVGs, images and existing Lottie files, and open any scene in Lottie Creator to fine-tune it frame by frame. Setup is one URL and a LottieFiles sign-in.
