ssyubix-pixelart-mcp

ssyubix-pixelart-mcp

MCP server (Python) for drawing pixel art and assembling 2D game tilesets. Built with MCP Python SDK v1.x (stable), stdio transport, designed to be used alongside unity-mcp-server in a single agent session.

Installation

From PyPI:

pip install ssyubix-pixelart-mcp

Or from source:

git clone https://github.com/syuaibsyuaib/ssyubix-pixelart-mcp
cd ssyubix-pixelart-mcp
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -e .

Running

python -m pixelart_mcp.server
# or, if installed from PyPI:
ssyubix-pixelart-mcp

Connecting to Claude Desktop / Claude Code

Add to claude_desktop_config.json (Claude Desktop) or via claude mcp add (Claude Code):

{
  "mcpServers": {
    "pixelart": {
      "command": "/path/to/ssyubix-pixelart-mcp/venv/bin/python",
      "args": ["-m", "pixelart_mcp.server"]
    }
  }
}

Tools List (24)

Drawing

• pixelart_create_canvas, pixelart_import_canvas, pixelart_set_pixel, pixelart_draw_line, pixelart_draw_rect, pixelart_draw_circle, pixelart_draw_polygon, pixelart_flood_fill

Canvas Management

• pixelart_clear_canvas, pixelart_flip_canvas, pixelart_duplicate_canvas, pixelart_get_canvas_info, pixelart_get_canvas_preview, pixelart_delete_canvas, pixelart_list_canvases

Color Palette

• pixelart_generate_palette, pixelart_extract_palette

Size Suggestion

• pixelart_suggest_tile_size, pixelart_suggest_tilemap_layout

Tileset

• pixelart_create_tileset, pixelart_set_tile, pixelart_export_tileset, pixelart_delete_tileset, pixelart_list_tilesets

Terminology: Tile vs Tileset vs Tilemap

These are easy to conflate and doing so produces broken/tiny output — a real bug that happened in production: an agent asked for a "tilemap" got back a single 32x32 canvas (that's a tile size) and shipped it as the whole map, which looked broken when used at real scale.

• Tile: one small square (e.g. 16x16px) — pixelart_create_canvas.
• Tileset: a sheet of many distinct tiles arranged in a grid (e.g. grass, path, water tile types) — pixelart_create_tileset + pixelart_set_tile + pixelart_export_tileset.
• Tilemap: a full level/map, composed of many tiles placed across a grid (built the same way as a tileset, but every slot is filled to represent the actual level layout) — never a single tile-sized canvas.

Typical Workflow

For a single asset/tile:

1. pixelart_suggest_tile_size (optional) — ask for ideal tile size based on object category or screen resolution.
2. pixelart_generate_palette — create color palette according to style/mood.
3. pixelart_create_canvas → pixelart_set_pixel / draw_line / draw_rect / draw_circle / flood_fill — draw a single tile.
4. pixelart_get_canvas_preview — view the result (upscaled PNG) before proceeding.

For a tileset or a full tilemap/level: 5. pixelart_suggest_tilemap_layout — get the grid (columns/rows) and total pixel size needed, from either an explicit tile count or a target screen/level size. 6. pixelart_create_tileset with that grid → pixelart_set_tile for every slot → pixelart_export_tileset. 7. The result of export_tileset is PNG + JSON metadata (tile size, grid, PPU) — the agent can then call unity-mcp-server tools to slice/import into a Unity project.

Running Tests

sh claude_tools/run_tests.sh

Structure

pixelart_mcp/
  server.py      # entry point, registers 23 tools
  canvas.py       # pixel drawing primitives
  palette.py      # palette generator
  sizing.py       # tile size heuristics
  tileset.py      # tileset assembly & export
  models.py       # Pydantic input models
  tests/          # 58 unit tests
claude_tools/     # helper script (dump schema, run tests)
task.md           # status & work notes
PUBLISHING.md      # guide to publish to PyPI & official MCP Registry

If unity-mcp-server is Not Available

pixelart_mcp is not technically dependent on unity-mcp-server — all tools above work fully without it. The difference is only in the final step: without unity-mcp-server, the result of pixelart_export_tileset (PNG + JSON metadata) must be imported manually into Unity Editor. Here are the steps (based on official Unity Manual), to guide an AI when helping a non-technical user:

1. Copy the exported PNG file to the Assets folder (or a subfolder like Assets/Sprites) within your Unity project.
2. In the Project window, click on the PNG file. In the Inspector panel:
   • Texture Type → Sprite (2D and UI)
   • Sprite Mode → Multiple (because it contains many tiles in one sheet)
   • Pixels Per Unit → enter the ppu value from the JSON metadata file
   • Filter Mode → Point (no filter) — to keep pixel art sharp, not blurred
   • Compression → None — to prevent color corruption
   • Click Apply.
3. Click the Sprite Editor button in the Inspector to open the Sprite Editor.
4. In the Sprite Editor, click the Slice dropdown, select Grid By Cell Size, then enter the Pixel Size with tile_width x tile_height from the JSON metadata.
5. Click Slice, then click Apply in the Sprite Editor toolbar.
6. Done — each tile is now a separate sprite that can be dragged directly into the Scene or used in a Tilemap.

All required values (tile_width, tile_height, ppu) are automatically available in the .json file generated by pixelart_export_tileset — the AI does not need to calculate them, just read them and guide the user through the steps above.

For AI Agents Maintaining/Developing This Project

Read AGENTS.md first — it contains the architecture map, mandatory conventions, checklist for adding new tools, and the workflow for handling user feedback/feature requests.

License

Apache License 2.0 — see LICENSE and NOTICE files.

Publishing to PyPI & MCP Registry

See PUBLISHING.md for complete guide (exact commands, requires personal credentials — PyPI token & GitHub OAuth login).

SDK Version Notes

This server is built on top of v1.x MCP Python SDK (stable, recommended for production). SDK v2 is still pre-release as of July 2026 — not used here per policy of "only stable/current official references".