# PixelForge

> PixelForge is an open-source MCP server for design and media. Generates pixel art sprites, animations and tilesets with Gemini from your assistant. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Repository:** https://github.com/freema/pixelforge-mcp
- **MCP Registry name:** io.github.freema/pixelforge-mcp
- **Categories:** [design and media](https://ai-powered.com/categories/design-and-media), [games and play](https://ai-powered.com/categories/games-and-play)
- **Listing updated:** 2026-11-18

## About

Image models tend to draw pixel art too large, blurry or on messy backgrounds. This server generates through Google Gemini and then cleans the result up: it removes the background, auto-crops, downsamples with area averaging rather than blurry bilinear scaling, and can pad to a square. A `chromakey` option generates on pure green and keys it out in HSV space for clean edges, which the README advises against for sprites that are themselves bright green.

Animations are generated frame by frame with the first frame passed as a reference so proportions and colours stay consistent, or as a single sheet that is split automatically. Item kits draw up to 16 related sprites on one grid and split them into separate PNGs. Style presets cover neon, retro, gameboy, snes and clean.

You supply your own Gemini API key, and the PNG pipeline has no native modules. The code is MIT licensed.

## Features

- **Sprite generation:** Creates a single sprite with automatic crop, background removal and downscale.
- **Animation frames:** Produces frame PNGs, using a reference chain for consistency.
- **Item kits:** Draws up to 16 related sprites in one batch and splits them.
- **Seamless tilesets:** Generates tileable square textures for terrain, floors and walls.
- **Chroma key transparency:** Keys out a green background in HSV space.
- **Style presets:** Neon, retro, gameboy, snes and clean looks, plus reference images to match style.

## Good for

- Make placeholder or final sprites for a game jam
- Generate walk or bounce animation frames
- Create seamless terrain tiles
- Split an existing sprite sheet into frames

## Install

### Claude Code (Terminal)

```sh
claude mcp add pixelforge-mcp --env GEMINI_API_KEY='<GEMINI_API_KEY>' -- npx -y pixelforge-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "pixelforge-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "pixelforge-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "<GEMINI_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "pixelforge-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "pixelforge-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "<GEMINI_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "pixelforge-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "pixelforge-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "<GEMINI_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "pixelforge-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "pixelforge-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "<GEMINI_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "pixelforge-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "pixelforge-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "<GEMINI_API_KEY>"
      }
    }
  }
}
```

## Tools

- `forge_sprite`: Generates one pixel art sprite with automatic post-processing.
- `forge_animation`: Generates animation frames as individual PNGs.
- `forge_background`: Generates a full game background without cropping.
- `forge_thumbnail`: Generates a game thumbnail or screenshot.
- `forge_tileset`: Generates a seamless tileable texture.
- `forge_item_kit`: Generates up to 16 related sprites in one batch.
- `process_sprite`: Removes backgrounds, crops and splits sprite sheets in an existing PNG.
- `optimize_sprite`: Downscales oversized AI images to true pixel art resolution.

## FAQ

### What do I need to run it?

Node.js 20 or newer and a Google Gemini API key.

### Which Gemini models can it use?

Aliases map to nano-banana-pro-preview (default), gemini-3.1-flash-image-preview, gemini-3-pro-image-preview and gemini-2.5-flash-image.

### What licence is it under?

MIT.

### Can it process images it did not generate?

Yes, process_sprite and optimize_sprite work on existing PNGs.

### Is PixelForge free?

Yes. PixelForge is open source, so you can use and self-host it for free.

### How do I add PixelForge to Claude Code?

Run this command in your terminal: claude mcp add pixelforge-mcp --env GEMINI_API_KEY='<GEMINI_API_KEY>' -- npx -y pixelforge-mcp

### What are the best alternatives to PixelForge?

The closest alternatives to PixelForge are HyperFrames by HeyGen, next-ai-draw-io, mcp-for-blender, ffmpeg-skill and cursor-talk-to-figma-mcp.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [HyperFrames by HeyGen](https://ai-powered.com/mcp/hyperframes-by-heygen): HyperFrames by HeyGen is a freemium MCP server for design and media.
- [next-ai-draw-io](https://ai-powered.com/mcp/next-ai-draw-io-2): next-ai-draw-io is an open-source MCP server for ai models and llm tooling.
- [mcp-for-blender](https://ai-powered.com/mcp/mcp-for-blender): mcp-for-blender is an open-source MCP server for design and media.
- [ffmpeg-skill](https://ai-powered.com/mcp/ffmpeg-skill): ffmpeg-skill is an open-source MCP server for design and media.
- [cursor-talk-to-figma-mcp](https://ai-powered.com/mcp/cursor-talk-to-figma-mcp): cursor-talk-to-figma-mcp is an open-source MCP server for design and media.
- [Digimon](https://ai-powered.com/mcp/digimon): Digimon is a freemium MCP server for games and play.
- [Clash Royale](https://ai-powered.com/mcp/clash-royale): Clash Royale is a freemium MCP server for games and play.
- [Design Feeds](https://ai-powered.com/mcp/design-feeds): Design Feeds is a freemium MCP server for design and media.

---
Source: https://ai-powered.com/mcp/pixelforge-2
