Spritesheet Forge MCP

A hosted Model Context Protocol (MCP) server for game-dev spritesheet workflows. Connect it to Claude or any MCP-compatible AI client and pack, split, trim, and animate sprites through natural language — no local tools required.

Server endpoint: https://mcp.clawstudiouo.com/mcp

Articles:
- GIF to Game-Ready Spritesheet with Claude MCP: A Complete Walkthrough — real demo: GIF → spritesheet → TexturePacker atlas JSON, with tool chaining and Unity/Godot integration notes
- Building a Remote MCP Server with Cloudflare Workers and GCP Cloud Run — technical deep-dive: OAuth 2.1 + PKCE, internal service auth, R2 file staging, and tool design for LLMs

---

Table of Contents

- What This Server Does
- Quick Start
- Authentication
- Tools Overview
- File Input Guide
- Tool Reference
- Working with AI Agents
- Limits & Quotas
- Benchmark
- FAQ
- Self-Hosting

---

What This Server Does

Spritesheet Forge exposes 7 image-processing tools over MCP. An AI agent calls them like any other tool — no shell commands, no local dependencies.

| Capability | Tools |
|------------|-------|
| GIF → spritesheet grid | gif_to_spritesheet |
| GIF → individual frames | gif_to_frames |
| Spritesheet → animated GIF/WebP | spritesheet_to_animation |
| Multiple PNGs → spritesheet | png_to_spritesheet |
| Spritesheet → split frames + atlas JSON | split_spritesheet |
| Frames → animated GIF/WebP | frames_to_animation |
| Trim transparent edges from PNGs | trim_png |

Typical agent workflows:

"Convert character.gif into a spritesheet for Unity"
→ gif_to_spritesheet
"Extract every frame from this animation, then trim the transparent borders"

→ gif_to_frames → trim_png (chained — output URL passed directly)
"Turn this spritesheet (4 columns × 3 rows) back into an animated GIF at 120ms per frame"

→ spritesheet_to_animation
"Pack these 12 sprites into a single atlas with a TexturePacker-compatible JSON"

→ png_to_spritesheet (layout=packed, metadata_format=json_hash)

Limitations

- Input formats: PNG, GIF, WebP
- Max file size: 20 MB per file
- Output TTL: Files expire 1 hour after creation — do not store output URLs for later
- Quota: 100 operations per GitHub account per month (free tier)
- Output format: Tools return a download URL; the server does not stream binary data directly

---

Quick Start

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

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

Restart Claude Desktop. On first use, Claude will open a GitHub login page to authorize access. After approval you can start using the tools immediately.

Claude Code (CLI)

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

Other MCP Clients

Any client that supports Streamable HTTP (MCP 2024-11-05 spec) can connect. Use:

- MCP endpoint: https://mcp.clawstudiouo.com/mcp
- Auth: OAuth 2.1 with PKCE (GitHub as IdP) — see Authentication
- Discovery: GET https://mcp.clawstudiouo.com/.well-known/oauth-authorization-server

---

Authentication

Spritesheet Forge uses GitHub OAuth 2.1 with PKCE. No API keys to create or rotate — you log in with GitHub and receive a long-lived session token.

How MCP clients handle it (recommended)

MCP clients like Claude Desktop and Claude Code run the OAuth flow automatically — they open a browser window, you approve the GitHub login, and the token is stored for you. No manual steps needed.

Getting a token manually (for benchmark / curl testing)

If you need a Bearer token directly — to run the benchmark script, test with curl, or integrate with a custom client — run this single command (requires Python 3, pre-installed on macOS/Linux):

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

This will:
1. Download the OAuth helper script directly from the server
2. Register a temporary OAuth client via RFC 7591
3. Open your browser to the GitHub authorization page
4. Exchange the code for a Bearer token, print it, and save it to ~/.spritesheet-forge-token

To test against a self-hosted instance:

python3 get-token.py --base-url https://your-worker.workers.dev

Token lifetime

Session tokens are valid for 30 days. After expiry, re-run the OAuth flow (or let your MCP client handle it automatically on the next connection).

---

Tools Overview

server_info

Returns this server's runtime configuration — upload endpoint URL, output TTL, file size limits, and encoding rules. Call this first when you need the exact upload URL or are planning a multi-step workflow.

{
  "upload_url": "https://mcp.clawstudiouo.com/upload",
  "output_ttl_seconds": 3600,
  "max_file_bytes": 20971520,
  "base64_threshold_bytes": 4194304,
  "file_input_rules": { ... }
}

gif_to_spritesheet

Converts a GIF animation into a spritesheet PNG. Frames are arranged in a grid; column count is auto-calculated from the frame count if not specified. Optional background removal.

gif_to_frames

Extracts every frame from a GIF and returns them as individual PNGs in a ZIP archive. Useful for editing single frames before reassembling.

spritesheet_to_animation

Slices a spritesheet back into frames and assembles them into an animated GIF or WebP. Supports both grid mode (columns + rows) and cell mode (cell_width + cell_height).

png_to_spritesheet

Merges multiple PNG files into a single spritesheet. Supports grid, horizontal, vertical, and packed (bin-packed) layouts. Can optionally output TexturePacker-compatible atlas JSON alongside the image.

split_spritesheet

The reverse of png_to_spritesheet — slices a spritesheet into individual frame PNGs, generates atlas JSON metadata, or both. Supports grid mode and cell mode.

frames_to_animation

Assembles a sequence of PNG frames into an animated GIF or animated WebP. Accepts frames in any order and sorts them by _N suffix if file_name_order=true.

trim_png

Crops transparent (alpha) edges from one or more PNG files. Single file returns a PNG; multiple files return a ZIP. Useful before packing sprites to remove wasted whitespace.

---

File Input Guide

All file / files parameters accept three input types:

1. Output URL from a previous tool call (fastest)

If you're chaining tools, just pass the output URL directly:

"file": "https://mcp.clawstudiouo.com/output/output-abc123.png"

The server reads from its own storage without making an HTTP request — this is always faster than re-uploading.

2. Base64 data URI (files < ~185 KB)

Encode the raw file bytes and prepend the MIME type:

"file": "data:image/gif;base64,R0lGODlh..."

> Important: You MUST strip ALL whitespace and newlines from the base64 string before prepending the prefix. Many base64 encoders (e.g. openssl base64, some shell tools) insert newlines every 76 characters — these will cause an INVALID_BASE64 error.

```bash

Correct — strips newlines

…