pixelforge-mcp

MCP server that forges pixel art sprites & game assets using Google Gemini — generate, crop, split & process, all from your AI assistant.

Features

• AI-powered generation — sprites, animations, backgrounds, thumbnails via Google Gemini
• Smart post-processing — background removal, auto-crop, pixelation downscale, square padding
• Sprite sheet splitting — auto-detect and split sheets into individual frames
• Style presets — neon, retro, gameboy, snes, clean
• Pure PNG pipeline — zero-dependency PNG encoder/decoder, no native modules
• Reference matching — pass existing sprites to match visual style

Installation

Claude Code (CLI)

claude mcp add pixelforge npx pixelforge-mcp@latest \
  --env GEMINI_API_KEY=your-api-key

Claude Code (Plugin)

/plugin marketplace add freema/pixelforge-mcp
/plugin install pixelforge-mcp

Restart Claude Code to load the MCP server (check with /mcp).

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pixelforge": {
      "command": "npx",
      "args": ["-y", "pixelforge-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Manual (any MCP client)

Add to your .mcp.json or equivalent config:

{
  "mcpServers": {
    "pixelforge": {
      "command": "npx",
      "args": ["-y", "pixelforge-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Requirements

• Node.js >= 20
• Google Gemini API key

Tools

forge_sprite

Generate a single pixel art sprite with automatic post-processing (crop, bg removal, downscale, square padding).

"Generate a green slime enemy sprite, 48px, retro style"

Required: description, outputPath Optional: size (default: 48), style, background, aspect, square, model, references

forge_animation

Generate animation frames as a sprite sheet, then auto-split into individual frame PNGs.

"Animate a slime bouncing, 4 frames"

Required: description, action, outputPrefix Optional: frames (default: 3), frameDescriptions, names, size, style, model, references

forge_background

Generate a full game background — no cropping, outputs the image as-is.

"Deep space background with stars and nebula, 16:9"

Required: description, outputPath, aspect Optional: style, model

forge_thumbnail

Generate a game thumbnail/screenshot. Pass references for visual consistency with your sprites.

"Space shooter scene with player ship vs alien rows"

Required: description, outputPath Optional: references, aspect (default: 4:3), style, model

process_sprite

Post-process an existing PNG — background removal, auto-crop, sprite sheet splitting.

"Split this sprite sheet into individual frames"

Required: inputPath Optional: outputPath, split, names, threshold, square, padding, skipCrop, skipTransparent

optimize_sprite

Downscale oversized AI images to true pixel art resolution using area-averaging (not blurry bilinear).

"Optimize this 1024px image down to 48px pixel art"

Required: inputPath, size Optional: outputPath, removeBackground, square

Full parameter docs: see docs/tools.md

Models

| Alias | Model ID | Notes | |-------|----------|-------| | nano-banana, banana | nano-banana-pro-preview | Default — best for pixel art | | flash, gemini-flash | gemini-3.1-flash-image-preview | Fast, reliable | | pro, gemini-pro | gemini-3-pro-image-preview | Best quality | | 25, gemini-25 | gemini-2.5-flash-image | Stable fallback |

Prompts

pixel_art_guide

Built-in MCP prompt with comprehensive pixel art generation guidelines — prompting rules, style tips, size recommendations, and best practices.

License

MIT — see LICENSE

Built by Tomas Grasl