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.

Related MCP server: Aseprite MCP Tools

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.

2. Procedural Texture Synthesis (generate_texture)

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

MCP Tools Matrix

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.