text2d — 2D Retro Pixel Art Texture MCP Server

A high-performance Model Context Protocol (MCP) server that empowers AI assistants to procedurally generate, manipulate, and export 2D retro pixel art textures and tilesets for game development.

---

Features

• Image to Retro Pixel Art Conversion: Ingest external PNG files and automatically downscale, quantize to retro palettes, and apply Bayer dithering via pixelize_image.
• Procedural Texture Synthesis: Deterministic generation of wood, stone (cobblestone/rock), brick, grass, metal (brushed plates with rivets), and water caustics.
• Pixel-Level Primitives: Full control via set_pixel, set_pixel_batch, draw_shape (lines, rects, circles), and flood_fill.
• Retro Palettes & Quantization: Built-in authentic color palettes including PICO-8, DawnBringer 32 (DB32), Endesga 32, GameBoy, NES Classic, and Cyberpunk Neon.
• Pixel-Art Post-Processing: Bayer ordered dithering (2x2, 4x4, 8x8) and 1px inner/outer pixel-perfect outlines.
• Export Options: PNG files with nearest-neighbor integer scaling, Base64 Data URIs, ASCII Unicode block previews, and 2D JSON color grids.

Visual Examples & Gallery

1. Image Pixelization (pixelize_image)

Convert high-resolution realistic photos or assets into authentic retro pixel art with automatic palette quantization and Bayer dithering.

Original Input	Endesga 32 (32x32)	PICO-8 (32x32)	GameBoy (32x32)
<img src="examples/input/realistic_car.jpg" width="160" alt="Original Photo" />	<img src="examples/output/car_pixel_32_endesga.png" width="160" alt="Endesga 32" />	<img src="examples/output/car_pixel_32_pico8.png" width="160" alt="PICO-8" />	<img src="examples/output/car_pixel_32_gameboy.png" width="160" alt="GameBoy" />

DawnBringer 32 (48x48)	Cyberpunk Neon (64x64)
<img src="examples/output/car_pixel_48_db32.png" width="200" alt="DB32 48x48" />	<img src="examples/output/car_pixel_64_cyberpunk.png" width="200" alt="Cyberpunk 64x64" />

2. Procedural Texture Synthesis (generate_texture)

Generate seamless, deterministic retro textures in seconds without external assets.

Wood (wood)	Stone (stone)	Brick (brick)
<img src="examples/output/wood.png" width="150" alt="Wood Texture" />	<img src="examples/output/stone.png" width="150" alt="Stone Texture" />	<img src="examples/output/brick.png" width="150" alt="Brick Texture" />

Grass (grass)	Metal (metal)	Water (water)
<img src="examples/output/grass.png" width="150" alt="Grass Texture" />	<img src="examples/output/metal.png" width="150" alt="Metal Texture" />	<img src="examples/output/water.png" width="150" alt="Water Texture" />

---

MCP Tools Matrix

Tool Name	Description	Key Parameters
pixelize_image	Ingests external PNG and converts to 2D retro pixel art	file_path, target_width, target_height, palette, sampling, dither, export_output_path
create_canvas	Initializes a new in-memory pixel canvas	width, height, palette, mode, backgroundColor
generate_texture	Synthesizes a procedural retro texture	canvas_id, texture_type, seed, palette, options
set_pixel	Sets a single pixel at (x, y)	canvas_id, x, y, color
set_pixel_batch	Batch updates multiple coordinates	canvas_id, pixels: [{x, y, color}]
draw_shape	Draws rasterized line, rect, or circle	canvas_id, shape, x1, y1, x2, y2, color, filled
flood_fill	Contiguous area flood fill	canvas_id, x, y, color
apply_dither	Applies Bayer ordered dithering	canvas_id, matrix_size, spread
apply_outline	Draws 1px pixel-perfect outline	canvas_id, color, mode
export_texture	Exports canvas to PNG, Data URI, ASCII or JSON	canvas_id, format, file_path, scale
list_palettes	Lists all built-in retro palettes	None
list_canvases	Lists active canvases in memory	None
get_canvas_info	Inspects canvas metadata and dimensions	canvas_id
delete_canvas	Frees canvas from memory	canvas_id

---

Installation & Usage

You can install and run text2d directly from GitHub without publishing to npm:

1. Global Installation (Recommended)

Install globally directly from the GitHub repository:

npm install -g github:al3duc/text2d-mcp

Once installed, the text2d command is available system-wide.

---

MCP Client Configuration

Add text2d to your MCP client configuration (e.g. claude_desktop_config.json, mcp_config.json, or Cursor):

Option A: Using Global Installation (Simplest)

{
  "mcpServers": {
    "text2d": {
      "command": "text2d"
    }
  }
}

Option B: Direct Execution via npx (No permanent install)

{
  "mcpServers": {
    "text2d": {
      "command": "npx",
      "args": [
        "-y",
        "github:al3duc/text2d-mcp"
      ]
    }
  }
}

Option C: Claude Code CLI Command

If using Claude Code, register it with a single terminal command:

claude mcp add text2d -- npx -y github:al3duc/text2d-mcp

Option D: Local Clone (Development)

git clone https://github.com/al3duc/text2d-mcp.git
cd text2d-mcp
npm install
npm run build

{
  "mcpServers": {
    "text2d": {
      "command": "node",
      "args": [
        "<PATH_TO_TEXT2D_REPOSITORY>/dist/index.js"
      ]
    }
  }
}

Note: Replace <PATH_TO_TEXT2D_REPOSITORY> with the absolute path to your cloned repository.

---

Build & Test

# Install dependencies
npm install

# Run unit & integration tests
npm test

# Build TypeScript to dist/
npm run build

# Generate procedural texture samples (wood, stone, brick, grass, metal, water)
npx tsx examples/generate_samples.ts

# Test converting realistic images from examples/input/ to pixel art
npx tsx examples/test_car_pixelize.ts

---

License

This project is licensed under the MIT License - see the LICENSE file for details.