Developers

15-Tool AI Agent MCP Server

Run the Python MCP server locally for pixel art, palettes, sprites, tilesets, and video tools.

PixelForge includes a Python MCP server in pixelforge/mcp_server.py. It speaks JSON-RPC over standard input/output and processes local files using the Python engine. It runs separately from the browser studio and the hosted static website.

Install and start#

Use Python 3.10 or newer. From your local PixelForge source checkout, install the package and its scientific/image-processing dependencies:

Terminal

python -m pip install -e .

Launch the server with the same Python interpreter:

Terminal

python -m pixelforge.mcp_server

After installation, the pixelforge-mcp command is also available in that Python environment. A server started manually waits for JSON-RPC messages on standard input; normally your MCP client starts it for you.

MCP client configuration#

Use the absolute path to the Python interpreter in which you installed PixelForge. For example, replace the placeholder below with your own interpreter path:

JSON

{
  "mcpServers": {
    "pixelforge": {
      "command": "C:/path/to/python.exe",
      "args": ["-m", "pixelforge.mcp_server"]
    }
  }
}

On macOS or Linux, use the corresponding absolute Python path. With an editable installation, keep the source checkout in place. The npm browser-studio launcher does not install this Python MCP server.

Available tools#

Tool	Description
`catalog_list`	Lists the Python engine's presets, styles, palettes, dithering methods, and pipeline modes.
`image_convert`	Converts a local image to pixel art and writes a PNG.
`image_stylize_reel`	Applies a procedural Reel style to an image.
`image_showcase`	Renders a contact sheet comparing styles or presets.
`image_detect_grid`	Detects an upscaled image's pixel grid and optionally recovers its native resolution.
`palette_tool`	Extracts, loads, or converts palettes, including optional Lospec imports.
`export_spritesheet`	Packs images or sampled video frames into a sprite sheet and atlas metadata.
`export_tileset`	Builds a tileset and tilemap with mirror-aware deduplication.
`video_convert`	Converts video to pixel-art MP4 or GIF.
`video_analyze_motion`	Analyzes scene cuts, zooms, and motion energy.
`video_sync_motion_to_audio`	Synchronizes motion to a WAV soundtrack and produces stylized video.
`video_detect_bar_fills`	Detects changing progress bars, meters, and gauges.
`video_detect_stroke_draws`	Detects progressively drawn indicators and outlines.
`video_extract_sound_triggers`	Extracts movement events for sound synchronization.
`studio_info`	Returns information and launch commands for the browser studio.

The server's tools/list response provides each tool's current input schema. Ask your MCP client to call catalog_list first to inspect the Python engine's available options, then use absolute local input and output paths for conversion tools.