Spritesheet Forge

Quick Start

Connect Spritesheet Forge to your AI client in under 2 minutes.

Claude Desktop

Add to claude_desktop_config.json (find it via Settings → Developer):

{
  "mcpServers": {
    "spritesheet-forge": {
      "type": "http",
      "url": "https://mcp.clawstudiouo.com/mcp"
    }
  }
}

Claude Code (CLI)

claude mcp add spritesheet-forge --transport http https://mcp.clawstudiouo.com/mcp

Authentication

Uses GitHub OAuth 2.1 with PKCE. MCP clients run the flow automatically. To get a Bearer token manually (for curl or benchmark scripts):

curl -O https://spritesheet-forge.spritesheet-forge.workers.dev/get-token.py && python3 get-token.py

Opens a GitHub login page, then prints and saves the token to ~/.spritesheet-forge-token. Requires Python 3 (pre-installed on macOS/Linux).

Tools

7 processing tools + 1 config tool. All inputs accept base64 data URIs, https:// URLs, or output URLs from previous tool calls.

gif_to_spritesheet GIF → PNG

Extracts all frames from an animated GIF and packs them into a spritesheet grid. Optionally removes the background from each frame.

Input — animated GIF

→

Output — spritesheet PNG

Parameter	Type	Default	Description
file	string	required	GIF file input
columns	integer	auto	Grid columns
padding	integer	0	Pixel gap between frames
remove_bg	boolean	false	Remove background from each frame
bg_color	string	"auto"	"auto" or "#RRGGBB"
tolerance	integer	30	Background removal threshold 0–255

spritesheet_to_animation PNG → GIF / WebP

Reassembles a spritesheet back into an animated GIF or WebP. Supports grid mode (columns × rows) or cell mode (fixed pixel dimensions). You can select frame ranges, trim offsets, and skip empty frames.

Input — spritesheet PNG (3×2 grid)

→

Output — animated GIF

Parameter	Type	Default	Description
file	string	required	Spritesheet PNG
columns	integer	—	Grid columns (grid mode)
rows	integer	—	Grid rows (grid mode)
cell_width	integer	—	Cell width px (cell mode)
cell_height	integer	—	Cell height px (cell mode)
frame_count	integer	—	Actual frames (for incomplete last row)
duration	integer	100	Frame duration in ms
loop	integer	0	Loop count (0 = infinite)
output_format	string	"gif"	"gif" | "webp"
skip_empty	boolean	true	Remove fully transparent frames

png_to_spritesheet PNGs → spritesheet

Packs multiple PNG files into a single spritesheet. Supports grid, horizontal, vertical, and bin-packed layouts. Optionally generates a JSON / CSS atlas for use in game engines.

Output — two frames packed horizontally

Parameter	Type	Default	Description
files	string[]	required	PNG files
layout	string	"grid"	"grid" | "horizontal" | "vertical" | "packed"
columns	integer	auto	Grid columns
padding	integer	0	Pixel gap between frames
metadata_format	string	"none"	"none" | "json_array" | "json_hash" | "css"
power_of_2	boolean	false	Pad output to next power of 2
trim_input	boolean	false	Auto-trim transparent edges before packing

frames_to_animation PNGs → GIF / WebP

Composes multiple PNG frames into an animated GIF or WebP. Frames are composited onto a shared canvas — mismatched sizes can be filled, padded with transparency, or rejected.

Output — two spritesheets composited into one animation

Parameter	Type	Default	Description
files	string[]	required	PNG frames
duration	integer	100	Frame duration ms
loop	integer	0	Loop count (0 = infinite)
output_format	string	"gif"	"gif" | "webp"
resize	string	"transparent"	"error" | "fill" | "transparent"
file_name_order	boolean	false	Sort by _N filename suffix

trim_png Crop transparent edges

Crops transparent (alpha) edges from one or more PNG files. Single file returns a PNG; multiple files return a ZIP. Useful for tightening sprite bounds before packing.

Before — original PNG

→

After — transparent edges removed

Parameter	Type	Default	Description
files	string[]	required	PNG files (single → PNG, multiple → ZIP)
threshold	integer	0	Alpha threshold 0–255
padding	integer	0	Transparent margin to preserve

File Input Guide

All file / files parameters accept three input types. Choose based on file size.

data:image/gif;base64,R0lGODl...

# Shell (no newlines)
base64 -i file.gif | tr -d '\n'

# Python (no newlines by default)
base64.b64encode(data).decode()

curl -X POST https://mcp.clawstudiouo.com/upload \
  -H "Authorization: Bearer <token>" \
  -F "file=@animation.gif"
# → { "url": "https://..." }

Chaining tool outputs

Pass the url from one tool directly as file input to the next — no re-encoding needed. The server reads chained URLs directly from its own storage with no HTTP overhead.

// Example chain: GIF → spritesheet → back to animation
const step1 = await gif_to_spritesheet({ file: gifDataUri, columns: 3 });
const step2 = await spritesheet_to_animation({ file: step1.url, columns: 3, rows: 2 });
// step2.url is the final animated GIF

Tool output format

Every tool returns a JSON object:

{
  "url": "https://mcp.clawstudiouo.com/output/output-abc123.png",
  "expires_at": "2026-05-05T13:00:00.000Z",
  "content_type": "image/png",
  "size_bytes": 516432,
  "quota": { "used": 4, "limit": 100, "reset_at": "2026-06-01T00:00:00.000Z" }
}

The url is also a direct browser-viewable download link.

Working with AI Agents

Tips for getting the best results when using Spritesheet Forge through Claude or another AI client.

Recommended context to give your agent

I've connected Spritesheet Forge MCP. For files ≥ 4 MB, call server_info
first to get the upload URL, then POST the file there before calling the
processing tool. Output URLs expire in 1 hour.

How the agent discovers this server

1. On initialize, the server returns an instructions field pointing to the public documentation page.
2. The agent fetches the docs page to learn about all tools, parameters, and file input rules.
3. For runtime config (upload URL, exact TTL), the agent calls server_info.

Getting a token for the upload endpoint

MCP clients (Claude Desktop, Claude Code) store their token in an encrypted internal store — there is no config file or keychain entry you can read. Run the one-line helper instead (Python 3, no extra dependencies):

curl -O https://spritesheet-forge.spritesheet-forge.workers.dev/get-token.py && python3 get-token.py

1. The script downloads, registers an OAuth client, and opens a GitHub login page.
2. Approve access in the browser.
3. The token is printed and saved to ~/.spritesheet-forge-token.
4. Pass it to your agent: "Here is my upload token: Bearer <token>"

Common errors

Limits & Quotas

Free tier limits. All limits are per GitHub account.

Benchmark

End-to-end latency measured from a local machine over the public endpoint (2026-05-05). All 11 tests passing.