Skip to main content
Glama
RosemyneH

pixel-art-factory

by RosemyneH
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Features

Capability

Description

Local generation

SDXL base + nerijs/pixel-art-xl LoRA via Hugging Face Diffusers

Pixel post-process

Downscale, palette quantization, transparency trim

Game presets

sprite, character, tile, icon, item, background

Batch manifests

JSON-driven asset packs in assets/manifests/

MCP tools

Six tools for Cursor agents and other MCP clients

Engine export

Spritesheet packing + Phaser atlas JSON

Related MCP server: mcp-image-tools

Requirements

  • GPU: NVIDIA with CUDA (8 GB+ VRAM recommended)

  • Python: 3.12+

  • Node.js: 20+

  • OS: Windows or Linux (setup scripts provided for both)

Quick start

1. Clone and install

Windows (PowerShell)

git clone https://github.com/RosemyneH/pixel-art-factory.git
cd pixel-art-factory
.\scripts\setup.ps1

Linux / macOS

git clone https://github.com/RosemyneH/pixel-art-factory.git
cd pixel-art-factory
./scripts/setup.sh

First run downloads PyTorch + SDXL models (~10–15 GB). Use -SkipModelDownload on Windows or SKIP_MODEL_DOWNLOAD=1 on Linux to defer until first generate.

2. Verify the engine

# Windows
.\.venv\Scripts\python.exe -m engine.cli status

# Linux / macOS
./.venv/bin/python -m engine.cli status

3. Generate a test asset

python -m engine.cli generate "green slime enemy" --type sprite --name slime

Output lands in assets/output/ with metadata in assets/output/.meta/.

Agent / MCP setup

Pixel Art Factory exposes a stdio MCP server that keeps the Python engine warm for fast repeated generations.

Step 1 — Build the MCP server

cd mcp-server
npm install
npm run build

Step 2 — Add to Cursor

Copy mcp.json.example into your Cursor MCP config:

Location

Scope

~/.cursor/mcp.json

Global (all projects)

<project>/.cursor/mcp.json

Single project

Replace <REPO_ROOT> with the absolute path to your clone.

Windows

{
  "mcpServers": {
    "pixel-art-factory": {
      "command": "node",
      "args": ["C:/path/to/pixel-art-factory/mcp-server/dist/index.js"],
      "env": {
        "PIXEL_FACTORY_PYTHON": "C:/path/to/pixel-art-factory/.venv/Scripts/python.exe"
      }
    }
  }
}

Linux / macOS

{
  "mcpServers": {
    "pixel-art-factory": {
      "command": "node",
      "args": ["/path/to/pixel-art-factory/mcp-server/dist/index.js"],
      "env": {
        "PIXEL_FACTORY_PYTHON": "/path/to/pixel-art-factory/.venv/bin/python"
      }
    }
  }
}

Step 3 — Restart Cursor

Open Settings → MCP and confirm pixel-art-factory shows as connected.

Step 4 — Smoke test (agent prompt)

Paste into any Cursor agent:

Call engine_status on pixel-art-factory, then generate_pixel_art with prompt "gold coin pickup" asset_type icon name coin_icon

MCP tools reference

Tool

Purpose

engine_status

GPU, CUDA, model, and output paths

generate_pixel_art

Single asset from a text prompt

batch_generate_assets

Run a manifest (e.g. starter-pack.json)

list_generated_assets

Browse recent outputs + metadata

create_spritesheet

Pack animation frames into one sheet

export_game_asset

Export Phaser atlas JSON for an asset

generate_pixel_art parameters

Param

Type

Default

Notes

prompt

string

required

What to generate

asset_type

enum

sprite

sprite character tile icon background item

width

number

64

Final pixel width

height

number

64

Final pixel height

palette_size

number

16

Color count after quantization

seed

number

—

Reproducible output

name

string

—

Output filename slug

tags

string[]

—

Stored in metadata

Batch manifests

Save to assets/manifests/<name>.json:

{
  "name": "starter-pack",
  "assets": [
    {
      "prompt": "wooden treasure chest closed",
      "asset_type": "item",
      "name": "chest_closed",
      "tags": ["loot"]
    },
    {
      "prompt": "grass ground tile top-down",
      "asset_type": "tile",
      "name": "grass_tile",
      "tags": ["terrain"]
    }
  ]
}

Run via CLI or MCP:

python -m engine.cli batch starter-pack.json
batch_generate_assets(manifest: "starter-pack.json")

Agent workflow tips

  1. Always call engine_status first — confirms GPU + model before a long batch.

  2. Use manifests for packs — one MCP call generates many assets with consistent presets.

  3. Name your assets — name becomes the filename; agents can reference it in export_game_asset.

  4. Tune presets — edit pipeline/presets.json for per-type sizes, steps, and prompt prefixes.

  5. Keep the engine warm — the MCP server holds the model loaded; avoid spawning separate CLI processes during agent sessions.

Project layout

pixel-art-factory/
├── engine/              # Python SDXL + pixel pipeline + CLI
├── mcp-server/          # TypeScript MCP bridge (stdio)
├── pipeline/            # Asset-type presets
├── assets/
│   ├── manifests/       # Batch job definitions
│   └── output/          # Generated PNGs (gitignored)
├── scripts/             # setup.ps1, setup.sh
├── tests/               # Pipeline unit tests
└── mcp.json.example     # Cursor MCP config template

Models

Role

Model

Base

stabilityai/stable-diffusion-xl-base-1.0

LoRA

nerijs/pixel-art-xl

VAE

stabilityai/sdxl-vae

Fallback

stabilityai/sdxl-turbo

Models download automatically on first run via engine.cli prefetch.

Development

# Run tests
python -m unittest discover -s tests -v

# Rebuild MCP server after TS changes
cd mcp-server && npm run build

License

MIT © 2026 RosemyneH

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers