Skip to main content
Glama

godot-sprite-mcp

CI License: MIT Python 3.10+

English | 简体中文

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.

Animated Demo

Collider Comparison

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 stable 54×112px torso collider, while preserving the wide 99×112px body on the slime.

✨ Features

MCP Tool

Description

inspect_spritesheet

Auto-detects grid cells or irregular sprite islands from the PNG alpha channel (supports res:// URIs).

build_sprite_frames

Generates Godot 4 (format=3) SpriteFrames .tres resources with AtlasTexture sub-resources.

build_body_collider

Overlays animation frames and uses a 30% vertical thickness filter to generate a stable, feet-aligned RectangleShape2D / CapsuleShape2D.

build_character_scene

Writes a complete Godot 4 .tscn character scene (CharacterBody2D + AnimatedSprite2D + feet-aligned CollisionShape2D).

extract_collision_polygon

Traces and simplifies outer pixel contours into a CollisionPolygon2D (<= 24 vertices) for static props.


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.png in project D:/my_game, create res://resources/knight_frames.tres with idle, run, and attack animations, and call build_character_scene to generate res://Knight.tscn."

  • "Analyze res://assets/slime.png and build a Slime.tscn with a feet-aligned body CollisionShape2D."


🛠️ 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 component islands when cells vary in size.

  • Movement Collider vs. Combat Hitboxes: build_body_collider produces 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

MIT

Available Tools

5 tools
build_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

    A4.1/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers