🎨 Pixel Art MCP

An MCP server that turns text prompts into cozy pixel-art PNGs — using a free, no-API-key image backend — and saves them straight into your project.

Point Claude (or any MCP client) at this server and ask for "a cozy library interior, side view, warm afternoon light"; it generates the image, crushes it down into authentic, palette-limited pixel art, and writes the PNG to disk. Built originally to make scene art for a pixel study-game, but useful for any game/app that needs quick, consistent pixel assets.

<!-- Replace with a real screenshot once you have one --> <!-- -->

---

✨ Features

• Text → pixel art in one call, saved as a ready-to-use PNG.
• Free by default — uses Pollinations (no API key, no signup).
• Real pixel-art post-processing — the model output is downscaled to a true pixel grid (nearest-neighbor) and palette-quantized, so it looks like pixel art, not just a blurry "pixel-ish" render.
• Pluggable backends — swap to Hugging Face (free token) or a local Stable Diffusion endpoint by changing one function / env var.
• Project-agnostic output — relative paths resolve against PIXEL_OUT_DIR, so the same server serves any project.
• Two tools: generate from a prompt, or pixelate an image you already have.
• Tiny & hackable — one server.py, ~200 lines, easy to extend.

🧠 How it works

MCP servers expose tools to an LLM. This one talks to the client (e.g. Claude Code) over stdio using JSON-RPC; the client launches it, lists its tools, and calls them when the model decides to.

prompt ──▶ style preamble ──▶ free image backend (HTTPS)
                                     │  raw image bytes
                                     ▼
                            Pillow: resize to WxH (NEAREST)
                                     │
                            quantize to N colors (median cut)
                                     ▼
                            save PNG ──▶ PIXEL_OUT_DIR/<out_path>

The "make it look like real pixel art" step is the downscale + palette quantize, not the model — that's the part worth keeping no matter which backend you use.

📦 Requirements

• Python 3.10+
• Outbound HTTPS at generation time (to the chosen backend)
• An MCP client (e.g. Claude Code)

🚀 Install

git clone https://github.com/uncagedspirit/pixel-art-mcp.git
cd pixel-art-mcp

python -m venv .venv
# Windows:
.venv/Scripts/python.exe -m pip install -r requirements.txt
# macOS / Linux:
# .venv/bin/python -m pip install -r requirements.txt

Optionally install it as a package (gives you a pixel-art-mcp command):

.venv/Scripts/python.exe -m pip install .

🔌 Register with Claude Code

Add an entry to your project's .mcp.json (or your global Claude config).

Windows

{
  "mcpServers": {
    "pixel-art": {
      "command": "C:/path/to/pixel-art-mcp/.venv/Scripts/python.exe",
      "args": ["C:/path/to/pixel-art-mcp/server.py"],
      "env": { "PIXEL_OUT_DIR": "C:/path/to/your/project" }
    }
  }
}

macOS / Linux

{
  "mcpServers": {
    "pixel-art": {
      "command": "/path/to/pixel-art-mcp/.venv/bin/python",
      "args": ["/path/to/pixel-art-mcp/server.py"],
      "env": { "PIXEL_OUT_DIR": "/path/to/your/project" }
    }
  }
}

Then restart Claude Code and approve the pixel-art server. The CLI alternative: claude mcp add pixel-art -- <python> <server.py>.

PIXEL_OUT_DIR sets where generated files land (defaults to the working directory). Set it to the project you want assets written into.

🛠️ Tools

generate_pixel_art(prompt, out_path, width=160, height=90, colors=32, seed=None)

Generate a pixel-art PNG from a prompt.

Arg	Meaning
prompt	What to draw
out_path	Where to save (relative → under PIXEL_OUT_DIR)
width,height	Pixel-grid size. 160x90 for 16:9 scenes; 32–64 for sprites
colors	Palette size; 16–32 reads as retro
seed	Optional, for reproducible results

pixelate_image(in_path, out_path, width=160, height=90, colors=32)

Pixelate an image you already have into a matching style.

🎚️ Backends

Set PIXEL_BACKEND:

Value	Free?	Setup
pollinations (default)	✅	nothing — no key
huggingface	free tier	set HF_TOKEN (and optionally HF_MODEL)

To use a local Stable Diffusion (best quality/control, needs a GPU), add a backend function that POSTs to your local endpoint (e.g. AUTOMATIC1111 / ComfyUI / SD.Next) and wire it into _generate_raw. The post-processing stays the same.

🧪 Quick test (without an MCP client)

.venv/Scripts/python.exe -c "import server; print(server.make_pixel_art('cozy cafe interior, side view, warm lamps', 'out/cafe.png', 160, 90, 32, 1))"

🗺️ Roadmap / ideas

• [ ] chroma_key tool — generate sprites on a solid background and key it out for transparent characters/props.
• [ ] Sprite-sheet / animation frames (e.g. N-frame idle loops, packed into a strip).
• [ ] Palette locking — pass a fixed palette so a whole asset set shares colors.
• [ ] Tileset / tilemap export (Tiled-friendly) for maps.
• [ ] Batch generation from a manifest (one call → a whole scene set).
• [ ] Upscaled preview output alongside the true-resolution PNG.
• [ ] More backends (Replicate, local ComfyUI workflow, Retro Diffusion).
• [ ] Optional background removal / auto-trim for props.
• [ ] Deterministic, seed-pinned regeneration + a small results gallery.

Contributions welcome — open an issue or PR.

🤝 Contributing

1. Fork & branch.
2. Keep server.py small; put new capabilities behind new @mcp.tool() functions.
3. Prefer pure helper functions (like make_pixel_art) so logic is testable without the MCP transport.
4. Update this README's tool list + roadmap.

⚠️ Notes

• Pollinations is a free community service: it can be slow/rate-limited and you should review its terms for your intended (especially commercial) use.
• This is a generation/dev tool. It makes network calls when generating; the output is plain local PNGs you commit into your project.

📄 License

MIT — do whatever, just keep the notice.