godot-sprite-mcp
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., "@godot-sprite-mcp Slice res://assets/knight_sheet.png and build Knight.tscn with feet-aligned colliders"
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.
godot-sprite-mcp
A lightweight Model Context Protocol (MCP) server & CLI for Godot 4.x that slices 2D spritesheets, exports SpriteFrames (.tres) animations, computes feet-aligned body colliders (CollisionShape2D), and generates ready-to-open .tscn character scenes directly from PNG alpha channels.
![]()
![]()
In the showcase above, even when computed across the broadsword attack row (
raw_width = 128px), the 30% vertical thickness filter automatically strips the 74px extended blade and keeps a stable54×112pxtorso collider, while preserving the wide99×112pxbody on the slime.
✨ Features
MCP Tool | Description |
| Auto-detects grid cells or irregular sprite islands from the PNG alpha channel (supports |
| Generates Godot 4 ( |
| Overlays animation frames and uses a 30% vertical thickness filter to generate a stable, feet-aligned |
| Writes a complete Godot 4 |
| Traces and simplifies outer pixel contours into a |
Related MCP server: blender-iso-mcp
🚀 Quick Start (MCP Configuration)
Prerequisites: Python 3.10+, Git, and uv (for uvx).
Add godot-sprite-mcp to your AI coding client (mcp.json in Cursor, Claude Code, Windsurf, Cline, Claude Desktop, etc.):
Option 1: Run directly from GitHub via uvx
{
"mcpServers": {
"godot-sprite": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/huha007/godot-sprite-mcp",
"godot-sprite-mcp"
]
}
}
}Option 2: Run from a local clone / Conda environment
git clone https://github.com/huha007/godot-sprite-mcp.git
cd godot-sprite-mcp
pip install -e .{
"mcpServers": {
"godot-sprite": {
"command": "godot-sprite-mcp"
}
}
}(On Windows with a virtual/Conda environment not on global PATH, set "command" to the full path of python.exe and "args": ["-m", "godot_sprite_mcp"].)
💬 Example Prompts for Your AI Agent
Once configured, ask your AI assistant in natural language:
"Inspect
res://assets/knight_sheet.pngin projectD:/my_game, createres://resources/knight_frames.treswithidle,run, andattackanimations, and callbuild_character_sceneto generateres://Knight.tscn.""Analyze
res://assets/slime.pngand build aSlime.tscnwith a feet-aligned bodyCollisionShape2D."
🛠️ CLI Usage (Standalone)
# 1. Inspect spritesheet layout (grid or islands)
godot-sprite-mcp inspect assets/knight_sheet.png --mode auto
# 2. Build Godot 4 SpriteFrames (.tres)
godot-sprite-mcp build \
--project-root . \
--image assets/knight_sheet.png \
--animations @animations.json \
--output res://resources/knight_frames.tres
# 3. Compute feet-aligned torso collider (RectangleShape2D / CapsuleShape2D)
godot-sprite-mcp body-collision assets/knight_sheet.png \
--frames @idle_frames.json \
--shape rectangle \
--thickness-ratio 0.30
# 4. Extract contour polygon for static props
godot-sprite-mcp collision assets/rock.png --epsilon 2.0⚠️ Scope & Limitations
PNG Alpha Channel Required: Frame detection and contour/collider extraction rely on transparent backgrounds (
alpha <= alpha_threshold). Solid-color opaque backgrounds must be made transparent first.Grid vs. Islands Mode:
mode="grid"expects fully transparent horizontal/vertical gutters and uniform cell sizes;mode="auto"automatically falls back to 8-connected componentislandswhen cells vary in size.Movement Collider vs. Combat Hitboxes:
build_body_colliderproduces a single stable physics collider for character movement (CharacterBody2D), rather than per-frame animated melee attack hitboxes (Area2D).
🧪 Running Tests
pip install -e ".[dev]"
pytest -v📄 License
Available Tools
5 toolsbuild_body_colliderA
Build a stable single-shape body collider for a moving character.
This is the recommended collision tool for player/enemy movement. It consumes all frames of one animation, overlays their alpha masks, measures the full character height and a thickness-filtered body width, and returns a feet-aligned RectangleShape2D (default) or CapsuleShape2D. The older extract_collision_polygon tool remains available for static objects.
Args:
image_path: Path or res:// URI to the spritesheet image.
frames: Every frame region of the selected animation, for example
[{"x": 0, "y": 264, "w": 66, "h": 66}, ...]. All frames must
have the same width and height.
shape: "rectangle" (default) or "capsule". Wide bodies such as
slimes use a rotated capsule automatically when capsule is chosen.
alpha_threshold: Pixels with alpha strictly greater than this are
opaque. Defaults to 10.
thickness_ratio: A column must have at least this fraction of the
character height to count as core body. Defaults to 0.30, which
filters thin weapons and arms.
project_root: Optional Godot project root directory for resolving
res:// URIs.
Returns:
A JSON-compatible dictionary containing height/top/bottom, filtered
body width and raw width, sprite_offset for the AnimatedSprite2D,
collision_position (feet at origin), shape parameters, and
ready-to-paste sub-resource and CollisionShape2D snippets.
Inputs: frames (required), image_path (required), shape, project_root, +2 more. Returns: object
build_character_sceneA
Write a complete Godot 4 .tscn character scene with AnimatedSprite2D and feet-aligned body collider.
Args:
project_root: Path to the Godot project directory containing project.godot.
image_path: Path or res:// URI to the spritesheet PNG.
sprite_frames_tres: Path or res:// URI to the generated SpriteFrames .tres resource.
output_tscn: Destination .tscn file path or res:// URI.
collider_frames: Frame regions (typically the idle animation row) used to compute the body collider.
root_name: Root node name in the scene (default: "Character").
root_type: Root node Godot class (default: "CharacterBody2D").
default_animation: Default animation name for the AnimatedSprite2D (default: "idle").
shape: "rectangle" (default) or "capsule".
alpha_threshold: Opaque alpha cutoff 0..255 (default: 10).
thickness_ratio: Minimum vertical column thickness ratio (default: 0.30).
Returns:
Metadata including the written output_tscn path, sprite_frames_res URI, and collider details.
Inputs: image_path (required), output_tscn (required), project_root (required), collider_frames (required), +7 more. Returns: object
build_sprite_framesA
Create a Godot 4.x SpriteFrames .tres resource from atlas regions.
This writes a format=3 Godot 4 resource. The image must live inside
project_root because Godot needs a res:// URI. Each animation
becomes an entry in the SpriteFrames animations array, and each frame
becomes an AtlasTexture sub-resource referencing the image.
Args:
project_root: Absolute path to the Godot project directory (the folder
containing project.godot).
image_path: Path to the spritesheet. It may be absolute, relative to
the project root, or already written as res://.... It must be
inside project_root.
animations: List of animation dictionaries. Example:
[{"name": "idle", "fps": 10.0, "loop": True, "frames": [ {"x": 0, "y": 0, "w": 32, "h": 32}, {"x": 32, "y": 0, "w": 32, "h": 32}]}].
Every animation requires a unique name and a frames list.
fps defaults to 10.0 and loop defaults to true. An optional
per-frame duration defaults to 1.0; playback timing is normally
controlled by the animation speed.
output_tres: Destination .tres path. An absolute path or res:// URI
is recommended; a relative path is resolved against
project_root. Parent directories are created automatically.
Returns:
Metadata including the absolute output_tres path, the Godot
texture_path URI, load_steps, animation_count and
frame_count.
Inputs: animations (required), image_path (required), output_tres (required), project_root (required). Returns: object
extract_collision_polygonA
Extract a simplified outer collision polygon from opaque pixels.
This optional tool is intended for static objects and irregular scenery. For moving characters and monsters, use build_body_collider instead to get a stable feet-aligned RectangleShape2D or CapsuleShape2D.
The largest external alpha contour is traced and simplified with the Ramer-Douglas-Peucker algorithm. The result is a simple clockwise polygon with at most 24 vertices, suitable for a CollisionPolygon2D.
Args:
image_path: Absolute path, relative path, or res:// URI to a PNG.
region: Optional sub-region {"x": int, "y": int, "w": int, "h": int}
in image pixels. When omitted, the whole image is used. Returned
coordinates are relative to this region's top-left corner.
epsilon: RDP simplification tolerance in pixels. Defaults to 2.0.
Larger values produce fewer vertices. If necessary the tolerance
is increased internally to keep the polygon at or below 24
vertices.
centered: When true (the default, matching Godot 4 Sprite2D), every
point is shifted so the coordinate origin is the image/region
centre. For a region of size w x h the conversion is
x - w / 2 and y - h / 2. Set to false to keep pixel-space
coordinates with a top-left origin.
project_root: Optional Godot project root directory for resolving
res:// URIs.
Returns:
A dictionary with points (list of [x, y]), vertex_count,
packed_vector2_array (Godot text such as
PackedVector2Array(0.0, -16.0, ...)) and tscn_snippet (a
CollisionPolygon2D node block ready to paste into a .tscn file).
Inputs: image_path (required), region, epsilon, centered, +1 more. Returns: object
inspect_spritesheetA
Inspect a PNG spritesheet and return frame rectangles.
Use this tool before building animations when you need to discover the
frame layout of a spritesheet. The alpha channel is analysed; pixels with
alpha strictly greater than alpha_threshold count as opaque.
Args:
image_path: Absolute path, relative path, or res://... URI to the
source PNG.
alpha_threshold: Opaque-pixel cutoff in the inclusive range 0..255.
Defaults to 10, so nearly transparent antialiasing is ignored.
mode: Detection strategy:
"grid" finds fully transparent horizontal/vertical separator lines,
"islands" finds 8-connected opaque islands and their tight bounding
boxes, and "auto" tries "grid" first and falls back to "islands"
when cell sizes are not uniform.
project_root: Optional Godot project root directory used to resolve
res:// URIs or relative paths.
Returns:
A JSON-compatible dictionary with image_width, image_height,
the detected mode, frame_count, and frames. Every frame is
{"id": int, "x": int, "y": int, "w": int, "h": int, "pivot_bottom_center": [float, float]}. Frames are ordered top to
bottom (row-clustered), then left to right.
Inputs: image_path (required), mode, project_root, alpha_threshold. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct stage of the pipeline (inspection, frame resource, collider, scene assembly), and the descriptions explicitly resolve the one real overlap by steering static objects to extract_collision_polygon and moving characters to build_body_collider. The only residual ambiguity is that build_character_scene composites the work of build_sprite_frames and build_body_collider, so an agent could pick the composite when it wanted just a sub-artifact.
All five names are snake_case verb_noun pairs (inspect_spritesheet, extract_collision_polygon, build_sprite_frames, build_body_collider, build_character_scene). The verb choice is semantically meaningful: 'inspect' for the read-only analysis tool, 'build' for the generators.
Five tools map cleanly onto a linear asset pipeline with no filler or redundancy. Every tool has an identifiable role and there is no thin one-tool surface nor a bloated menu.
The core workflow (discover frames -> SpriteFrames resource -> collider -> full character scene) is fully covered end to end. Minor gaps exist: no tool to read/validate or amend an existing .tres/.tscn, no TileSet or non-character sprite output, and no way to re-inspect previously generated assets.
Maintenance
Related MCP Connectors
Generate, search and export game-ready sprite sheets for Godot, Unity and other game engines.
Generate game sprite sheets and animations from an image, and clean up sprite backgrounds.
Create AI animations and export transparent sprite sheets, alpha video, frames, and game assets.
AI game assets for agents: consistent sprites, 2D animations, tiles, maps, music and engine exports.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables any MCP-compatible AI agent to programmatically create, edit, import/export spritesheets, and save .pxo projects in Pixelorama via a Godot extension and file-queue transport.-
- AlicenseBqualityCmaintenanceEnables AI agents to procedurally design and render stylized 2:1 dimetric isometric game assets in Blender, including NPR cel-shaded scenes, modular tilesets, 8-angle avatar turnarounds, and mathematically exact subpixel collision diamonds, with turnkey engine manifests for Phaser, Godot 4, and retro web games.10Apache 2.0
- AlicenseNot gradedqualityCmaintenanceConverts a single character image into game-ready 2D sprite animations (walk, run, idle, attack, etc.) with transparent frames, sprite sheets, and metadata, usable from AI coding agents.MIT
- AlicenseAqualityBmaintenanceEnables users to create character spritesheets from natural-language requests, preview animations, search clothing and tool items, and export engine-ready assets for Godot, Unity, and web.41150 PyPI1MIT