Pixellab MCP

PixelLab MCP Server

Generate pixel art game assets (characters, animations, tilesets) directly from code using the PixelLab MCP Server.

Overview

The PixelLab MCP Server provides tools for generating pixel art game assets programmatically. All creation operations are non-blocking - they return immediately with job IDs and process in the background (typically 2-5 minutes).

Server URL: https://api.pixellab.ai/mcp

Setup

The MCP server is already configured and enabled. You can call these tools directly - they will be available in your tool list.

Non-Blocking Operations

CRITICAL CONCEPT: All creation tools return immediately with job IDs - they process in the background (2-5 minutes):

• Submit request → Get job ID instantly
• Process runs in background
• Check status with corresponding get_* tool
• Download when ready (UUID serves as access key)
• No authentication needed for downloads - share download links freely

This means you should:

1. Submit creation requests
2. Continue with other work or check status periodically
3. Download assets when status indicates completion

Available Tools

Character Tools

• create_character - Create a new character sprite
• animate_character - Add animations to an existing character
• get_character - Get character status and download URLs
• list_characters - List all your characters
• delete_character - Delete a character

Top-Down Tileset Tools

• create_topdown_tileset - Create a top-down tileset (16 Wang tiles)
• get_topdown_tileset - Get tileset status and download URLs
• list_topdown_tilesets - List all your top-down tilesets
• delete_topdown_tileset - Delete a tileset

Sidescroller Tileset Tools

• create_sidescroller_tileset - Create a sidescroller tileset
• get_sidescroller_tileset - Get tileset status and download URLs
• list_sidescroller_tilesets - List all your sidescroller tilesets
• delete_sidescroller_tileset - Delete a tileset

Isometric Tile Tools

• create_isometric_tile - Create an isometric tile
• get_isometric_tile - Get tile status and download URLs
• list_isometric_tiles - List all your isometric tiles
• delete_isometric_tile - Delete a tile

Character Creation Workflow

Basic Character Creation

# Create a character with 4 directions
character = create_character(
    description="A brave knight with red armor and a sword",
    n_directions=4,  # or 8 for more directions
    size=48,  # Canvas size in pixels
    proportions='{"type": "preset", "name": "heroic"}'
)
# Returns: { "character_id": "uuid", "status": "processing" }

Direction Options

• 4 directions: south, west, east, north
• 8 directions: adds south-east, north-east, north-west, south-west

Character Sizing

• Canvas size: Character will be ~60% of canvas height
• Example: 48px canvas = ~29px tall character
• Common sizes: 32px, 48px, 64px

Proportions

Use preset proportions or custom:

• '{"type": "preset", "name": "heroic"}' - Heroic proportions
• '{"type": "preset", "name": "chibi"}' - Chibi/cute proportions
• Custom proportions can be specified as JSON

Adding Animations

Queue animations immediately after creation:

# Create character first
character_id = create_character(...)["character_id"]

# Queue walk animation
animate_character(character_id, 'walk')

# Other animation templates:
# - 'walk'
# - 'running-8-frames'
# - 'jumping-1'
# - And more...

Checking Status

# Check if character is ready
status = get_character(character_id)
# Returns: { "status": "completed", "download_url": "...", ... }

Character Storage

• Characters are stored permanently and can be reused
• Characters created via MCP appear in web interfaces (Character Creator) if using same account
• Use list_characters() to see all your characters

Tileset Creation

Top-Down Tilesets

Creates 16 Wang tiles for seamless terrain:

tileset = create_topdown_tileset(
    lower_description="Grassy terrain with small rocks",
    upper_description="Dirt path with stones"
)
# Returns: { "tileset_id": "uuid", "status": "processing" }

Use Cases:

• Overworld maps
• Strategy games
• RPGs with top-down view
• Seamless terrain generation

Chain tilesets for consistency:

# Create base tileset
base = create_topdown_tileset(...)

# Create related tileset using base for consistency
related = create_topdown_tileset(
    lower_description="Sandy beach",
    upper_description="Ocean water",
    base_tile_id=base["tileset_id"]  # Links to base for visual consistency
)

Sidescroller Tilesets

For 2D platformers:

tileset = create_sidescroller_tileset(
    lower_description="Stone platform with cracks",
    transition_description="Grass-to-stone transition"
)
# Returns: { "tileset_id": "uuid", "status": "processing" }

Use Cases:

• 2D platformers
• Side-scrolling games
• Metroidvania-style games

Isometric Tiles

For 3D-looking game assets:

tile = create_isometric_tile(
    description="Medieval stone block with moss",
    size=32,  # Recommended: 32px or larger (24px minimum)
    tile_shape='block'  # Options: 'block', 'floor', etc.
)
# Returns: { "tile_id": "uuid", "status": "processing" }

Use Cases:

• Isometric games
• 3D-looking 2D games
• Strategy games with isometric view

Size Recommendations:

• Minimum: 24px
• Recommended: 32px or larger
• Larger sizes produce better quality

Key Tips and Best Practices

Canvas and Sizing

• Character canvas size: Character will be ~60% of canvas height (e.g., 48px canvas = ~29px tall character)
• Tile sizes: Typically 16x16 or 32x32 pixels for tilesets
• Isometric tiles: Sizes above 24px produce better quality (32px recommended)

Animation Templates

Use template_animation_id parameter with values like:

• 'walk' - Standard walk cycle
• 'running-8-frames' - Running animation with 8 frames
• 'jumping-1' - Jump animation
• Check available templates in documentation

Download URLs

• UUID acts as access key - no authentication required for downloads
• Share download links freely
• Download URLs are permanent

Integration with Web Interfaces

• Characters/tilesets created via MCP appear in web interfaces (Character Creator, Map Workshop) if using same account
• You can continue editing in web interfaces after creation

Chaining Tilesets

• Use base_tile_id parameters to chain tilesets for visual consistency across terrain types
• Useful for creating related terrain sets (e.g., grass → dirt → stone transitions)

Status Checking

• All creation operations are asynchronous
• Poll get_* tools periodically to check status
• Typical processing time: 2-5 minutes
• Status values: "processing", "completed", "failed"

Available Resources

Documentation Resources

Access these via pixellab://docs/ URLs:

• pixellab://docs/overview - Complete platform overview
• pixellab://docs/godot/wang-tilesets - Godot 4.x Wang tileset implementation
• pixellab://docs/godot/sidescroller-tilesets - Godot 4.x sidescroller implementation
• pixellab://docs/godot/isometric-tiles - Godot 4.x isometric tiles guide
• pixellab://docs/unity/isometric-tilemaps-2d - Unity 2D isometric tilemap guide
• pixellab://docs/python/wang-tilesets - Python Wang tileset implementation
• pixellab://docs/python/sidescroller-tilesets - Python sidescroller implementation

Example Workflows

Complete Character Creation

# 1. Create character
character = create_character(
    description="A brave knight with red armor",
    n_directions=8,
    size=48,
    proportions='{"type": "preset", "name": "heroic"}'
)
character_id = character["character_id"]

# 2. Queue animations
animate_character(character_id, 'walk')
animate_character(character_id, 'running-8-frames')

# 3. Check status (poll until ready)
import time
while True:
    status = get_character(character_id)
    if status["status"] == "completed":
        print(f"Download: {status['download_url']}")
        break
    elif status["status"] == "failed":
        print("Creation failed")
        break
    time.sleep(10)  # Wait 10 seconds before checking again

Tileset Chain for Terrain

# Create base grass tileset
grass = create_topdown_tileset(
    lower_description="Lush green grass",
    upper_description="Grass with small flowers"
)

# Create dirt tileset linked to grass
dirt = create_topdown_tileset(
    lower_description="Brown dirt path",
    upper_description="Dirt with footprints",
    base_tile_id=grass["tileset_id"]
)

# Create stone tileset linked to dirt
stone = create_topdown_tileset(
    lower_description="Gray stone floor",
    upper_description="Stone with cracks",
    base_tile_id=dirt["tileset_id"]
)

Tool Parameters Reference

create_character

• description (string, required) - Character description
• n_directions (int, optional) - Number of directions (4 or 8, default: 4)
• size (int, optional) - Canvas size in pixels (default: 48)
• proportions (string, optional) - JSON string with proportions (default: heroic preset)

animate_character

• character_id (string, required) - Character UUID
• template_animation_id (string, required) - Animation template name

create_topdown_tileset

• lower_description (string, required) - Description for lower layer
• upper_description (string, required) - Description for upper layer
• base_tile_id (string, optional) - Base tileset ID for visual consistency

create_sidescroller_tileset

• lower_description (string, required) - Description for lower layer
• transition_description (string, required) - Description for transition
• base_tile_id (string, optional) - Base tileset ID for visual consistency

create_isometric_tile

• description (string, required) - Tile description
• size (int, optional) - Tile size in pixels (default: 32, minimum: 24)
• tile_shape (string, optional) - Tile shape type (default: 'block')

Error Handling

• Check status regularly - operations may fail
• Failed operations will have status: "failed" in response
• Retry creation if needed
• Download URLs are only available when status is "completed"