pixellab-mcp

PixelLab MCP Server

Model Context Protocol (MCP) server for PixelLab pixel art generation and manipulation. This server enables AI assistants like Claude to generate, edit, and manipulate pixel art using PixelLab's AI-powered API.

Features

• 🎨 Generate Pixel Art: Create characters, items, and environments from text descriptions
• 🎭 Style Transfer: Generate pixel art using reference images for style matching
• 🔄 Image Rotation: Generate rotated views of characters and objects
• ✏️ Inpainting: Edit existing pixel art by painting in specific regions
• 🦴 Skeleton Estimation: Extract skeleton structure from character images
• 💰 Balance Checking: Monitor PixelLab API credits
• 👁️ AI Vision: Generated images are immediately visible to AI assistants

Installation

Prerequisites

• Node.js 18 or higher (required for MCP SDK compatibility)
• PixelLab API key (get one at pixellab.ai)

Install Globally (Required for MCP Clients)

For use with MCP clients like Cursor, Claude Desktop, etc., you must install globally:

npm install -g pixellab-mcp

Configuration

Add to your MCP client configuration (e.g., Cursor or Claude Desktop) with your PixelLab secret:

{
  "mcpServers": {
    "pixellab": {
      "command": "npx",
      "args": ["pixellab-mcp", "--secret=your-pixellab-secret-here"]
    }
  }
}

Available Tools

1. generate_image_pixflux

Generate pixel art from text descriptions using PixelLab's Pixflux model.

Parameters:

• description (required): Text description of what to generate (e.g., "cute dragon with sword", "medieval knight")
• width (default: 64): Image width in pixels (recommended: 32, 64, 128, 256)
• height (default: 64): Image height in pixels (recommended: 32, 64, 128, 256)
• negative_description (optional): What to avoid in the generation (e.g., "blurry, ugly, distorted")
• text_guidance_scale (default: 8.0): How closely to follow the text description (1.0-20.0)
• no_background (default: false): Generate without background (useful for sprites)
• outline (optional): Outline style ("single color black outline", "selective outline", "lineless", etc.)
• shading (optional): Shading style ("flat shading", "basic shading", "detailed shading", etc.)
• detail (optional): Detail level ("low detail", "medium detail", "highly detailed")
• save_to_file (optional): Path to save the generated image (e.g., "./dragon.png")
• show_image (default: false): Show the generated image to the AI assistant for viewing

2. generate_image_bitforge

Generate pixel art using a reference image for style matching (Bitforge model).

Parameters:

• description (required): Text description of what to generate (e.g., "warrior holding shield")
• style_image_path (required): Path to reference style image
• width (default: 64): Image width in pixels (recommended: 32, 64, 128, 256)
• height (default: 64): Image height in pixels (recommended: 32, 64, 128, 256)
• style_strength (default: 50.0): How strongly to match the style (0-100)
• no_background (default: false): Generate without background
• save_to_file (optional): Path to save the generated image (e.g., "./styled_character.png")
• show_image (default: false): Show the generated image to the AI assistant for viewing

3. rotate

Generate rotated views of characters and objects.

Parameters:

• image_path (required): Path to character/object image
• from_direction (optional): Current direction ("south", "east", "north", "west", etc.)
• to_direction (required): Direction to rotate to ("south", "east", "north", "west", etc.)
• width (default: 64): Image width in pixels (recommended: 32, 64, 128, 256)
• height (default: 64): Image height in pixels (recommended: 32, 64, 128, 256)
• save_to_file (optional): Path to save the rotated image (e.g., "./character_east.png")
• show_image (default: false): Show before/after comparison to the AI assistant

4. inpaint

Edit existing pixel art by inpainting specific regions.

Parameters:

• image_path (required): Path to image to edit
• mask_path (required): Path to mask image (white = edit, black = keep)
• description (required): Description of what to paint in the masked area (e.g., "red hat", "golden armor")
• width (default: 64): Image width in pixels (recommended: 32, 64, 128, 256)
• height (default: 64): Image height in pixels (recommended: 32, 64, 128, 256)
• save_to_file (optional): Path to save the edited image (e.g., "./character_with_hat.png")
• show_image (default: false): Show before/after comparison to the AI assistant

5. estimate_skeleton

Extract skeleton structure from character images.

Parameters:

• image_path (required): Path to character image
• show_image (default: false): Show the original image with skeleton data to the AI assistant

6. animate_with_skeleton

Create animated pixel art sequences using skeleton keyframes. Define keypoints for different poses to create smooth animations.

Parameters:

• skeleton_frames (required): Array of skeleton frames defining the animation sequence
  • Each frame contains keypoints array with x, y, label, and optional z_index
  • Supported labels: "NOSE", "NECK", "RIGHT SHOULDER", "RIGHT ELBOW", "RIGHT ARM", "LEFT SHOULDER", "LEFT ELBOW", "LEFT ARM", "RIGHT HIP", "RIGHT KNEE", "RIGHT LEG", "LEFT HIP", "LEFT KNEE", "LEFT LEG", "RIGHT EYE", "LEFT EYE", "RIGHT EAR", "LEFT EAR"
• reference_image_path (optional): Path to reference image for character appearance
• width (default: 64): Image width in pixels (recommended: 32, 64, 128, 256)
• height (default: 64): Image height in pixels (recommended: 32, 64, 128, 256)
• view (default: "side"): Camera viewpoint ("side", "low top-down", "high top-down")
• direction (default: "east"): Character facing direction ("south", "east", "north", "west", etc.)
• reference_guidance_scale (default: 1.1): How closely to follow reference image (1.0-20.0)
• pose_guidance_scale (default: 3.0): How closely to follow skeleton poses (1.0-20.0)
• isometric (default: false): Use isometric projection
• oblique_projection (default: false): Use oblique projection
• init_image_strength (default: 300): Strength of initialization images (0-1000)
• seed (default: 0): Random seed for reproducible results
• save_to_file (optional): Path template to save animation frames (e.g., "./animation.png")
• show_image (default: false): Show the generated animation frames to the AI assistant

7. animate_with_text

Create animated pixel art sequences from text descriptions. Requires a reference character image and describes the action to animate.

Parameters:

• description (required): Description of the character to animate (e.g., "knight in armor", "wizard with staff")
• action (required): Action to animate (e.g., "walking", "swinging sword", "casting spell")
• reference_image_path (required): Path to reference character image to animate
• width (default: 64): Image width in pixels (recommended: 32, 64, 128, 256)
• height (default: 64): Image height in pixels (recommended: 32, 64, 128, 256)
• view (default: "side"): Camera viewpoint ("side", "low top-down", "high top-down")
• direction (default: "east"): Character facing direction ("south", "east", "north", "west", etc.)
• negative_description (optional): What to avoid in the animation (e.g., "blurry, distorted")
• text_guidance_scale (default: 7.5): How closely to follow text description (1.0-20.0)
• image_guidance_scale (default: 1.5): How closely to follow reference image (1.0-20.0)
• n_frames (default: 4): Number of animation frames to generate (1-20)
• start_frame_index (default: 0): Starting frame index (for continuing animations)
• init_image_strength (default: 300): Strength of initialization images (1-999)
• seed (default: 0): Random seed for reproducible results
• save_to_file (optional): Path template to save animation frames (e.g., "./walk_cycle.png")
• show_image (default: false): Show the generated animation frames to the AI assistant

8. get_balance

Check available PixelLab API credits.

Parameters: None

Usage Examples

Once configured with your MCP client, you can use natural language to interact with PixelLab:

• "Generate a pixel art dragon with a sword"
• "Create a pixel art character in the style of this reference image"
• "Rotate this character sprite to face east"
• "Add a hat to this character using inpainting"
• "Analyze the skeleton structure of this character"
• "Create a walking animation for this character"
• "Animate this knight swinging a sword"
• "Check my PixelLab balance"

The AI assistant will call the appropriate tools and display the generated pixel art immediately when show_image is enabled.

Command Line Usage

You can also run the server directly:

# Production usage (recommended)
pixellab-mcp --secret=your-pixellab-secret

# Development with local API server
pixellab-mcp --secret=your-secret --base-url=http://localhost:8000/v1

# Using environment variables
PIXELLAB_SECRET=your-secret pixellab-mcp

# Show help
pixellab-mcp --help

Development

Setup

git clone <repository-url>
cd pixellab-mcp
npm install

Build

npm run build

Run in Development

npm run dev -- --secret=your-test-secret

Test with MCP Inspector

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Test the server (production)
mcp-inspector npx pixellab-mcp --secret=your-test-secret

# Test with local development server
mcp-inspector npx pixellab-mcp --secret=your-test-secret --base-url=http://localhost:8000/v1

Architecture

This MCP server is built as a lightweight wrapper around the @pixellab-code/pixellab library, providing:

• Modular Design: Each tool is implemented in its own file for maintainability
• Type Safety: Full TypeScript support with Zod validation
• Error Handling: Comprehensive error handling and user-friendly messages
• AI Vision: Optional image visibility to AI assistants via MCP image protocol
• File Management: Optional file saving with automatic path handling
• Flexible Configuration: Command line arguments or environment variables

Tool Architecture

The server implements 8 modular tools:

• src/tools/generatePixelArt.ts - Pixflux text-to-pixel-art generation
• src/tools/generatePixelArtWithStyle.ts - Bitforge style-transfer generation
• src/tools/getBalance.ts - API credit checking
• src/tools/rotateCharacter.ts - Character rotation with comparisons
• src/tools/inpaintPixelArt.ts - Region-based editing with comparisons
• src/tools/estimateSkeleton.ts - Skeleton detection with visualization
• src/tools/animateWithSkeleton.ts - Skeleton-based animation generation
• src/tools/animateWithText.ts - Text-based animation generation

Dependencies

• @modelcontextprotocol/sdk: MCP server framework
• @pixellab-code/pixellab: PixelLab JavaScript client
• zod: Runtime type validation
• dotenv: Environment variable management

Troubleshooting

MCP Server Connection Issues

Problem: MCP client shows "Connection closed" or "No server info found"

Solution: Ensure the package is installed globally:

npm install -g pixellab-mcp

Problem: Server starts but immediately exits

Causes & Solutions:

1. Invalid API key: Verify your PixelLab secret is correct
2. Package not found: Install globally (see above)
3. Node.js version: Ensure Node.js 18+ is installed
4. Directory issues: Use absolute paths if needed:

{
  "mcpServers": {
    "pixellab": {
      "command": "node",
      "args": ["/path/to/pixellab-mcp/dist/index.js", "--secret=your-secret"]
    }
  }
}

Problem: Server shows fewer than 8 tools

Solution: You should see these 8 tools:

• generate_image_pixflux
• generate_image_bitforge
• get_balance
• rotate
• inpaint
• estimate_skeleton
• animate_with_skeleton
• animate_with_text

If you see fewer, try:

1. Restart your MCP client completely
2. Reinstall globally: npm uninstall -g pixellab-mcp && npm install -g pixellab-mcp
3. Check for conflicting server configurations

Testing the Server

Test manually before adding to MCP client:

# Test help (should show usage)
pixellab-mcp --help

# Test server startup (should show "PixelLab MCP Server running on stdio")
timeout 5s pixellab-mcp --secret=your-secret

License

MIT

Support

• PixelLab API: docs.pixellab.ai
• MCP Protocol: modelcontextprotocol.io
• Issues: Create an issue in this repository