ssyubix-pixelart-mcp

ssyubix-pixelart-mcp

ピクセルアートの描画と2Dゲームのタイルセットの組み立てに対応したMCP サーバー（Python）です。 MCP Python SDK v1.x（安定版）を使用し、 stdio トランスポートで動作します。単一のエージェントセッションで unity-mcp-server と併用するように設計されています。

インストール

PyPIから：

pip install ssyubix-pixelart-mcp

ソースから：

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 .

実行

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

Claude Desktop / Claude Code への接続

claude_desktop_config.json（Claude Desktop）に追加するか、 claude mcp add（Claude Code）を実行します：

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

ツール一覧（24）

描画

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

キャンバス管理

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

カラーパレット

• pixelart_generate_palette、pixelart_extract_palette

サイズの提案

• pixelart_suggest_tile_size、pixelart_suggest_tilemap_layout

タイルセット

• pixelart_create_tileset、pixelart_set_tile、pixelart_export_tileset、pixelart_delete_tileset、pixelart_list_tilesets

用語：タイル、タイルセット、タイルマップの違い

これらは混同しやすく、混同すると出力が壊れたり極端に小さくなったりします。実際に本番環境で発生したバグでは、エージェントが「タイルマップ」を求めたところ、32x32のキャンバスが返されました（これは タイル のサイズです）。それをマップ全体として出荷したため、実際のスケールで使うと見た目が壊れていました。

• タイル：小さな正方形ひとつ（例：16x16px）— pixelart_create_canvas。
• タイルセット：グリッド状に並べた複数の異なるタイルのシート（例：草、道、水のタイルタイプ）— pixelart_create_tileset + pixelart_set_tile + pixelart_export_tileset。
• タイルマップ：グリッド上に複数のタイルを配置して構成する、レベル／マップ全体（タイルセットと同じ方法で作成しますが、実際のレベルレイアウトを表すためにすべてのスロットを埋めます）— タイルサイズのキャンバスひとつだけで作るものではありません。

一般的なワークフロー

単一のアセット／タイルの場合：

1. pixelart_suggest_tile_size（任意）— オブジェクトのカテゴリや画面解像度に基づいて、最適なタイルサイズを確認します。
2. pixelart_generate_palette — スタイルや雰囲気に合わせてカラーパレットを作成します。
3. pixelart_create_canvas → pixelart_set_pixel / draw_line / draw_rect / draw_circle / flood_fill — 単一のタイルを描画します。
4. pixelart_get_canvas_preview — 次に進む前に、結果を（拡大したPNGで）確認します。

タイルセットまたはタイルマップ／レベル全体の場合： 5. pixelart_suggest_tilemap_layout — 明示的なタイル数、または目標とする画面／レベルサイズに基づいて、必要なグリッド（列／行）と合計ピクセルサイズを取得します。 6. そのグリッドを指定して pixelart_create_tileset を実行し、すべてのスロットに対して pixelart_set_tile を実行してから、pixelart_export_tileset を実行します。 7. export_tileset の結果はPNGとJSONメタデータ（タイルサイズ、グリッド、PPU）です。その後、エージェントは unity-mcp-server のツールを呼び出して、Unityプロジェクトにスライス／インポートできます。

テストの実行

sh claude_tools/run_tests.sh

構成

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

unity-mcp-server を利用できない場合

pixelart_mcp は技術的には unity-mcp-server に依存していません。上記のすべてのツールは、これがなくても完全に動作します。違いは最後の手順だけです。unity-mcp-server がない場合は、pixelart_export_tileset の出力（PNG と JSON メタデータ）を Unity Editor に手動でインポートする必要があります。技術に詳しくないユーザーを支援する際に AI が案内できるよう、以下に公式の Unity Manual に基づく手順を示します。

1. エクスポートした PNG ファイルをコピーし、Unity プロジェクト内の Assets フォルダー（または Assets/Sprites などのサブフォルダー）に配置します。
2. Project ウィンドウで PNG ファイルをクリックします。Inspector パネルで以下を設定します。
   • Texture Type → Sprite (2D and UI)
   • Sprite Mode → Multiple（1 枚のシートに複数のタイルが含まれているため）
   • Pixels Per Unit → JSON メタデータファイルの ppu の値を入力します
   • Filter Mode → Point (no filter) — ピクセルアートがぼやけず、鮮明に表示されるようにします
   • Compression → None — 色の破損を防ぎます
   • Apply をクリックします。
3. Inspector の Sprite Editor ボタンをクリックして、Sprite Editor を開きます。
4. Sprite Editor で Slice ドロップダウンをクリックし、Grid By Cell Size を選択して、JSON メタデータの tile_width x tile_height を Pixel Size に入力します。
5. Slice をクリックし、Sprite Editor のツールバーで Apply をクリックします。
6. これで完了です。各タイルが個別のスプライトになり、Scene に直接ドラッグしたり、Tilemap で使用したりできます。

必要な値（tile_width、tile_height、ppu）は、pixelart_export_tileset が生成する .json ファイルに自動的に含まれています。AI が計算する必要はなく、値を読み取って上記の手順をユーザーに案内するだけです。

このプロジェクトの保守・開発を行う AI エージェント向け

まず AGENTS.md を読んでください。アーキテクチャの概要、必須の規約、新しいツールを追加する際のチェックリスト、ユーザーからのフィードバックや機能リクエストに対応するためのワークフローが記載されています。

ライセンス

Apache License 2.0 — LICENSE ファイルと NOTICE ファイルを参照してください。

PyPI と MCP Registry への公開

詳細なガイド（正確なコマンド、個人認証情報が必要 — PyPI トークンと GitHub OAuth ログイン）については、PUBLISHING.md を参照してください。

SDK バージョンに関する注意事項

このサーバーは v1.x MCP Python SDK を基盤として構築されています（安定版であり、本番環境での使用が推奨されています）。2026 年 7 月時点で SDK v2 はまだプレリリース版のため、「安定した最新の公式リファレンスのみを使用する」という方針に従い、ここでは使用していません。