Aseprite Live MCP

Codexから、開いているAsepriteの作品を見ながらドット絵を描き、レイヤー・アニメーションを編集してゲーム用に書き出すMCPです。Mac上で動作し、このMCP用のクラウド契約や追加の画像生成APIキーは必要ありません。Codex自体の利用条件・料金は別です。

あなたの指示 → Codex → MCP → Mac内の接続用プログラム → 開いているAseprite
                    ← 作品情報・画像プレビュー ←

絵を考えるのは接続したCodexのモデルです。このMCPはピクセル単位の描画・確認・修正の道具を提供します。別の画像生成モデルは内蔵していません。

必要な環境

macOS、Node.js 22以降、Aseprite、ローカルMCPに対応したCodexが必要です。Aseprite 1.3.18.3-arm64で動作確認しています。これより古いバージョン、Windows・Linuxは未検証です。

セットアップ

このフォルダーで依存ライブラリと接続ファイルを準備します。
```
npm ci
npm run setup
```
Asepriteの Edit → Preferences → Extensions → Add Extension から、生成された artifacts/codex-live-bridge.aseprite-extension を追加します。通常の File → Open は作品用なので使いません。
Codexの Settings → MCP servers → Add server で、生成された artifacts/codex-config.toml にある command と args を設定します。CLIを使える場合は、このフォルダーで次のコマンドでも登録できます。
```
codex mcp add aseprite -- "$(command -v node)" "$(pwd)/src/server.mjs"
```
CodexのMCP設定で Restart を実行します。Asepriteの File → Connect to Codex を選び、Codexで「Asepriteの接続状態を確認して」と指示します。接続用プログラムは最初のツール呼び出しで自動起動します。
「新しく32×32のスライムを描いて。体と顔をレイヤーに分けて、待機アニメーションを4コマ作って」のように依頼します。現在の作品を編集したい場合は「いま開いている作品を確認して」と明示すると対象を合わせやすくなります。

接続が成功するとAsepriteのステータスバーに Connected to Codex と表示されます。接続操作後は次回起動時にも自動で接続を試みます。File → Disconnect from Codex で切断すると、自動接続も停止します。

Asepriteが初めての接続やコピー保存を確認する場合は、対象を確認して Allow to Open Connections または Allow Write Access を選びます。Give full trust to this script は必要ありません。45秒以内に許可できなかった場合は、処理が終わっているか確認してから再開します。

できること

機能	Codexへの依頼例
作品確認・プレビュー	「現在の絵とレイヤーを確認して」
描画・レイヤー編集	「武器を別レイヤーに描いて」「輪郭を濃くして」
RGB・Indexed編集	「Indexedで作って」「パレットの2番を赤にして」
選択・回転・拡大縮小	「選択部分を時計回りに90度回して、2倍にして」
レイヤー・コマ削除	「下書きレイヤーを削除して」「最後の2コマを削除して」
タイルマップ	「8×8の草タイルを作って床に並べて」
GIF出力	「待機アニメーションをループGIFにして」
アニメーション編集	「歩行を4コマ追加して、walkという名前にして」
PNG・スプライトシート出力	「全コマを横4列で書き出して」
編集可能なコピー保存	「レイヤーを残したAseprite形式のコピーも保存して」

レイヤーは絵の部品、フレームは動きの各コマ、タグは「待機・歩行・攻撃」などのコマ範囲です。詳細は機能資料にあります。

保存と取り消し

AIの編集は開いている作品に即時反映され、1回の編集ツール呼び出しがAsepriteの1回のUndoになります。長い依頼を複数回のツールに分けた場合は、取り消しも複数回です。自動で元ファイルを上書き保存することはありません。通常の保存はAsepriteから行ってください。

書き出し先は初期設定でこのプロジェクトの exports/ です。PNGとJSONは exports/指定名/spritesheet.png と spritesheet.json に、編集可能なコピーは別の新しいフォルダーに保存します。同名フォルダーがあればエラーになり、既存の内容を上書きしません。

対応範囲

編集はRGB・Indexedの両形式に対応し、新規作成はIndexedが既定です。最大512×512、128レイヤー、256フレームが対象です。Indexedは色番号を維持し、未登録の色はパレットへ追加します。256色で満杯の場合はエラーとし、近似色に置き換えません。

選択範囲とセル単位の回転・拡大縮小・反転、レイヤー・コマ削除、標準タイルマップの作成・タイル絵・配置編集に対応します。ロックされたレイヤーや親グループ、背景・参照レイヤーへの描画は未対応です。タイルマップには専用操作を使います。Grayscaleは確認・プレビューのみです。

スプライトシートは透過RGBA PNGとAseprite形式に近いJSONです。フレームはトリミングせず等間隔に配置し、コマ時間とタグを含めます。1回の出力は最大256コマ・約400万ピクセルです。GIF出力は透過とコマ時間、ループ回数に対応します。GIFの半透明は透明／不透明に分け、コマ時間は10ミリ秒単位に丸めます。ゲームエンジンへの自動登録、ボーンアニメーション、画像ファイルの取り込み、キャンバス全体の寸法変更は未実装です。

接続できないとき

状態	対応
Codexにツールが表示されない	MCP設定の登録・再読み込みと、`command` のNode.jsパスを確認する
`Aseprite is not connected`	Asepriteで `Connect to Codex` を選ぶ。メニューがなければExtensionsから追加を確認する
`Document changed`	人の編集や別の依頼が先に反映されたため、作品を再確認してから続ける
`timed out` / `disconnected`	Asepriteのダイアログを閉じて接続を確認する。直前の処理が反映済みの可能性があるため、再実行前に作品を確認する
出力名が既に存在する	別の出力名を指定する

接続は 127.0.0.1:47118 のみで待ち受け、認証用トークンを使います。外部サイト由来の接続は拒否します。.local/ と生成された個人用拡張パッケージには接続情報が含まれるため、配布対象に含めないでください。ソースを別のMacへ移し、そのMacで npm run setup を行うと別の接続情報を作れます。

複数のCodexタスクは1つの接続用プログラムを共有します。同時編集は受け付けず、別の処理が進行中ならエラーを返します。1つの接続用プログラムに接続できるAsepriteのプロセスは1つです。AsepriteもMCPも利用していない状態が10分続くと、接続用プログラムは停止します。

開発・検証

npm run check
npm test
npm run test:aseprite

test:aseprite は別のバッチプロセスでテスト作品を作り、既存のGUI作品を操作しません。Asepriteの場所が異なる場合は ASEPRITE_PATH を指定します。

GUIで接続後に次を実行すると、実際のMCP経由で新しいテスト作品を作り、画像プレビュー・アニメーション・PNG/JSON・GIF出力・Aseprite形式のコピー、選択・変形・削除・タイルマップとRGB・Indexed編集を確認します。既存の作品は閉じません。

npm run test:live

生成結果は artifacts/live/ と exports/live-demo-* に記録します。テスト結果・確認範囲は検証記録を参照してください。

拡張の更新時は npm run setup -- --install-aseprite を実行し、Asepriteの Preferences → Extensions → Codex Live Bridge → Disable → Enable で再読み込みできます。開いている作品を閉じる必要はありません。Codex側もMCP設定を再読み込みして新しいツール定義を取得します。

接続設定は .local/bridge.json にあります。変更後は拡張を再生成・更新し、接続用プログラムとCodex MCPを再起動してください。ASEPRITE_MCP_CONFIG で別の設定ファイルを使う構成も可能ですが、拡張の接続先・トークンと一致させる必要があります。

参照

Aseprite公式API、WebSocket、拡張機能、Codex公式MCP設定。