{
  "markdown": "# ssyubix-pixelart-mcp\n\n<!-- mcp-name: io.github.syuaibsyuaib/ssyubix-pixelart-mcp -->\n\n[![GitHub Downloads](https://img.shields.io/github/downloads/syuaibsyuaib/ssyubix-pixelart-mcp/total?logo=github)](https://github.com/syuaibsyuaib/ssyubix-pixelart-mcp/releases)\n[![PyPI Downloads](https://img.shields.io/pypi/dm/ssyubix-pixelart-mcp?logo=python)](https://pypi.org/project/ssyubix-pixelart-mcp/)\n[![Python](https://img.shields.io/badge/Python-99.6%25-3776ab?logo=python)](https://github.com/syuaibsyuaib/ssyubix-pixelart-mcp)\n\nMCP server (Python) for drawing pixel art and assembling 2D game tilesets.\nBuilt with [MCP Python SDK v1.x](https://github.com/modelcontextprotocol/python-sdk)\n(stable), **stdio** transport, designed to be used alongside\n`unity-mcp-server` in a single agent session.\n\n## Installation\n\nFrom PyPI:\n```bash\npip install ssyubix-pixelart-mcp\n```\n\nOr from source:\n```bash\ngit clone https://github.com/syuaibsyuaib/ssyubix-pixelart-mcp\ncd ssyubix-pixelart-mcp\npython3 -m venv venv\nsource venv/bin/activate   # Windows: venv\\Scripts\\activate\npip install -e .\n```\n\n## Running\n\n```bash\npython -m pixelart_mcp.server\n# or, if installed from PyPI:\nssyubix-pixelart-mcp\n```\n\n## Connecting to Claude Desktop / Claude Code\n\nAdd to `claude_desktop_config.json` (Claude Desktop) or via\n`claude mcp add` (Claude Code):\n\n```json\n{\n  \"mcpServers\": {\n    \"pixelart\": {\n      \"command\": \"/path/to/ssyubix-pixelart-mcp/venv/bin/python\",\n      \"args\": [\"-m\", \"pixelart_mcp.server\"]\n    }\n  }\n}\n```\n\n## Tools List (24)\n\n**Drawing**\n- `pixelart_create_canvas`, `pixelart_import_canvas`, `pixelart_set_pixel`, `pixelart_draw_line`, `pixelart_draw_rect`, `pixelart_draw_circle`, `pixelart_draw_polygon`, `pixelart_flood_fill`\n\n**Canvas Management**\n- `pixelart_clear_canvas`, `pixelart_flip_canvas`, `pixelart_duplicate_canvas`, `pixelart_get_canvas_info`, `pixelart_get_canvas_preview`, `pixelart_delete_canvas`, `pixelart_list_canvases`\n\n**Color Palette**\n- `pixelart_generate_palette`, `pixelart_extract_palette`\n\n**Size Suggestion**\n- `pixelart_suggest_tile_size`, `pixelart_suggest_tilemap_layout`\n\n**Tileset**\n- `pixelart_create_tileset`, `pixelart_set_tile`, `pixelart_export_tileset`, `pixelart_delete_tileset`, `pixelart_list_tilesets`\n\n## Terminology: Tile vs Tileset vs Tilemap\n\nThese are easy to conflate and doing so produces broken/tiny output — a\nreal bug that happened in production: an agent asked for a \"tilemap\" got\nback a single 32x32 canvas (that's a *tile* size) and shipped it as the\nwhole map, which looked broken when used at real scale.\n\n- **Tile**: one small square (e.g. 16x16px) — `pixelart_create_canvas`.\n- **Tileset**: a sheet of many distinct tiles arranged in a grid (e.g. grass,\n  path, water tile types) — `pixelart_create_tileset` + `pixelart_set_tile` + `pixelart_export_tileset`.\n- **Tilemap**: a full level/map, composed of many tiles placed across a grid\n  (built the same way as a tileset, but every slot is filled to represent\n  the actual level layout) — never a single tile-sized canvas.\n\n## Typical Workflow\n\n**For a single asset/tile:**\n1. `pixelart_suggest_tile_size` (optional) — ask for ideal tile size based on object category or screen resolution.\n2. `pixelart_generate_palette` — create color palette according to style/mood.\n3. `pixelart_create_canvas` → `pixelart_set_pixel` / `draw_line` / `draw_rect` / `draw_circle` / `flood_fill` — draw a single tile.\n4. `pixelart_get_canvas_preview` — view the result (upscaled PNG) before proceeding.\n\n**For a tileset or a full tilemap/level:**\n5. `pixelart_suggest_tilemap_layout` — get the grid (columns/rows) and total pixel\n   size needed, from either an explicit tile count or a target screen/level size.\n6. `pixelart_create_tileset` with that grid → `pixelart_set_tile` for **every** slot → `pixelart_export_tileset`.\n7. The result of `export_tileset` is PNG + JSON metadata (tile size, grid, PPU) —\n   the agent can then call `unity-mcp-server` tools to slice/import into a Unity project.\n\n## Running Tests\n\n```bash\nsh claude_tools/run_tests.sh\n```\n\n## Structure\n\n```\npixelart_mcp/\n  server.py      # entry point, registers 23 tools\n  canvas.py       # pixel drawing primitives\n  palette.py      # palette generator\n  sizing.py       # tile size heuristics\n  tileset.py      # tileset assembly & export\n  models.py       # Pydantic input models\n  tests/          # 58 unit tests\nclaude_tools/     # helper script (dump schema, run tests)\ntask.md           # status & work notes\nPUBLISHING.md      # guide to publish to PyPI & official MCP Registry\n```\n\n## If `unity-mcp-server` is Not Available\n\n`pixelart_mcp` is **not technically dependent** on `unity-mcp-server` —\nall tools above work fully without it. The difference is only in the final step:\nwithout `unity-mcp-server`, the result of `pixelart_export_tileset` (PNG +\nJSON metadata) must be imported manually into Unity Editor. Here are the steps\n(based on official Unity Manual), to guide an AI when helping a non-technical user:\n\n1. **Copy the exported PNG file** to the `Assets` folder (or a subfolder like\n   `Assets/Sprites`) within your Unity project.\n2. In the **Project** window, click on the PNG file. In the **Inspector** panel:\n   - **Texture Type** → `Sprite (2D and UI)`\n   - **Sprite Mode** → `Multiple` (because it contains many tiles in one sheet)\n   - **Pixels Per Unit** → enter the `ppu` value from the JSON metadata file\n   - **Filter Mode** → `Point (no filter)` — to keep pixel art sharp, not blurred\n   - **Compression** → `None` — to prevent color corruption\n   - Click **Apply**.\n3. Click the **Sprite Editor** button in the Inspector to open the Sprite Editor.\n4. In the Sprite Editor, click the **Slice** dropdown, select **Grid By Cell Size**,\n   then enter the **Pixel Size** with `tile_width` x `tile_height` from the JSON metadata.\n5. Click **Slice**, then click **Apply** in the Sprite Editor toolbar.\n6. Done — each tile is now a separate sprite that can be dragged directly into the\n   Scene or used in a Tilemap.\n\nAll required values (`tile_width`, `tile_height`, `ppu`) are automatically\navailable in the `.json` file generated by `pixelart_export_tileset`\n— the AI does not need to calculate them, just read them and guide the user\nthrough the steps above.\n\n## For AI Agents Maintaining/Developing This Project\n\nRead `AGENTS.md` first — it contains the architecture map, mandatory conventions,\nchecklist for adding new tools, and the workflow for handling user feedback/feature requests.\n\n## License\n\nApache License 2.0 — see `LICENSE` and `NOTICE` files.\n\n## Publishing to PyPI & MCP Registry\n\nSee `PUBLISHING.md` for complete guide (exact commands, requires personal\ncredentials — PyPI token & GitHub OAuth login).\n\n## SDK Version Notes\n\nThis server is built on top of **v1.x** MCP Python SDK (stable, recommended\nfor production). SDK v2 is still pre-release as of July 2026 — not used here\nper policy of \"only stable/current official references\".\n",
  "bytes": 6947,
  "sha": "7b62166743e7fecbd73c02cb0840e4b86707c366767a403a31c0a6e9a0853c28",
  "repo_slug": "syuaibsyuaib/ssyubix-pixelart-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_syuaibsyuaib_ssyubix_pixelart__8a1b86f9/readme"
}