rpgmaker-mz-mcp

クイックスタート

Claude Code（推奨） — サーバーと制作スキルをプラグインとしてまとめてインストールします。

claude plugin marketplace add Redseb/rpgmaker-mz-mcp
claude plugin install rpgmaker-mz@rpgmaker-mz-mcp

RPG Maker MZ プロジェクトのディレクトリを尋ねられます（省略可能です。後から Claude に set_project を実行するよう依頼することもできます）。

その他の MCP クライアント — サーバーは npm で公開されているため、クローンやビルドは不要です。

{
  "mcpServers": {
    "rpgmaker-mz": {
      "command": "npx",
      "args": ["-y", "rpgmaker-mz-mcp@latest"],
      "env": { "RPGMAKER_PROJECT_PATH": "/path/to/your/rpgmaker/project" }
    }
  }
}

Claude Desktop — 上記の JSON 設定を使用するか、Releases からワンクリックで使える rpgmaker-mz-mcp.mcpb バンドルをダウンロードし、Claude Desktop で開いてください。

初めて使う方は、手順全体を説明した SETUP.md と、最初から最後までの手順例を紹介する EXAMPLES.md をご覧ください。

目次

• クイックスタート
• 機能
• 全体の仕組み
• インストール
• 設定
• 使い方
• 利用可能なツール
• 入力の検証
• イベントの検証（デフォルトで例外をスロー）
• 参照の lint
• ドライランプレビュー
• カスタムタイルセットカタログスキル
• プロンプト例
• 開発
• プロジェクト構成
• 安全性とベストプラクティス
• 制限事項

機能

• データベース CRUD — アクター、職業（習得スキルとパラメータ曲線を含む）、スキル（フルコントロールと、ダメージ／回復／強化／ステートの簡易ヘルパー）、アイテム、武器、防具、ステート、敵キャラ、敵グループを扱えます。作成に必要なのは name だけです。それ以外はすべて、エディターの実際の「新規 X」テンプレートに従います。
• マップとマップツリー — マップの作成／削除、循環を防止しながらの一括親変更／並べ替え／名前変更、マッププロパティの編集ができます。新しいマップは、エディターが想定する形式で MapInfos.json に登録されます。
• タイル描画（オートタイル自動処理付き） — paint_tiles／fill_area で6つのマップレイヤーのいずれにもタイルを設定でき、同種タイルの隣接状況からオートタイルの形状（および隣接タイルの形状）を再計算するため、塗りつぶした領域の境界も正しくつながります。paint_blueprint はASCII行と凡例を使って、領域全体を1回の呼び出しで描画します（複数レイヤーのセル、カタログ名、自動生成されるA4壁面）。通行可否の概要も返します。place_object は複数タイルのB／Cオブジェクト（家、木など）を配置し、通行可否の範囲を報告します。
• セマンティックタイルカタログ — find_tile "grass" → 描画可能なタイルID。すべてのデフォルトタイルセット（Overworld、Outside、Inside、Dungeon、SF）に対応した組み込みカタログを備えています。カタログの情報源は、RPG Maker に付属する英語名のサイドカーファイルです。バンドルされたビジョンブートストラップスキルは、カスタムタイルセットをカタログ化します。
• 通行可否と地形 — タイルのフラグまたはマップセルのレイヤー別通行可否を確認し（get_tile_flags／check_passability）、通行可否／地形タグ／挙動フラグを編集できます（set_tile_flags）。
• イベントコマンドビルダー — エディターが書き込むものと完全に同一の EventCommand シーケンスを生成する、高レベルの読み取り専用ビルダーです（複雑な再帰分岐ブロックや継続行も含みます）。insert_event_commands でページに追加できます。会話とフロー、ゲーム状態の変更、演出／トランジション、シーン処理に対応しています。
• イベントとNPCの利便性 — create_npc は会話可能なNPC一式を1回の呼び出しで配置します。set_event_page はページの画像と挙動をその場でマージします。
• アセットの把握 — list_assets は有効なキャラクター／顔画像／タイルセット／オーディオの名前を列挙するため、イベントが存在しないファイルを参照することはありません。
• ビルドを確認してプレイ — render_map はマップ全体またはゲーム画面表示で、エンジンが描画するものとまったく同じマップのスクリーンショットを生成します。run_playtest はスクリプト化されたヘッドレスセッションを実行します（状態の読み込み、イベントの発生、会話の確認、選択肢の選択、移動、自動戦闘、スクリーンショット）。どちらもコンソールエラーと不足しているアセットを報告します。バリデーターは構造を検証し、これらの機能はプレイヤーに見えるものを示します。
• 正確性のレイヤー — Zodによる入力検証、デフォルトで例外を発生させるイベント検証（構造的に無効な書き込みは、保存して警告するのではなく拒否されます）、ファイル横断参照リンター（validate_references）、すべての書き込みに対するドライラン／差分プレビューを備えています。

連携の仕組み

インストール

次のいずれかを選択してください。

• Claude Code プラグイン (推奨) — claude plugin marketplace add Redseb/rpgmaker-mz-mcp を実行し、続けて claude plugin install rpgmaker-mz@rpgmaker-mz-mcp を実行します。MCP サーバー（npm パッケージから npx 経由で実行）と、2つのオーサリングスキル（rpgmaker-authoring、tileset-catalog）がセットになっています。スキルはツールでは強制できない判断を補うため、すべての機能を利用できます。
• npm パッケージ — MCP クライアントが npx -y rpgmaker-mz-mcp@latest を実行するように設定します（クイックスタートを参照）。ツールのみで、スキルは含まれません。
• MCPB バンドル（Claude Desktop） — Releases から rpgmaker-mz-mcp.mcpb をダウンロードし、Claude Desktop で開いて、インストールダイアログでプロジェクトフォルダーを選択します。
• ソースからインストール（開発用）：

npm install
npm run build

設定

RPG Maker MZ プロジェクトのパスを環境変数として設定します。

# macOS/Linux
export RPGMAKER_PROJECT_PATH=/path/to/your/rpgmaker/project

# Windows
set RPGMAKER_PROJECT_PATH=C:\path\to\your\rpgmaker\project

パスは、game.rmmzproject と System.json を含む data/ ディレクトリが存在するディレクトリを指している必要があります。

環境変数は起動時のデフォルトにすぎません。set_project ツールを使えば、実行中のサーバーの対象を別のプロジェクトに変更でき（get_project で現在のプロジェクトを確認できます）、ゲームを切り替える際に設定の編集や再起動は不要です。

使い方

サーバーの実行

npm start          # or: node dist/index.js

Claude Desktop での設定

最も簡単な方法は、Releases にある .mcpb バンドルを使うことです。Claude Desktop で開き、プロジェクトフォルダーを選択してください。手動で設定する場合は、Claude Desktop の設定ファイル（Windows では %APPDATA%\Claude\claude_desktop_config.json、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）に次を追加します。

{
  "mcpServers": {
    "rpgmaker-mz": {
      "command": "npx",
      "args": ["-y", "rpgmaker-mz-mcp@latest"],
      "env": {
        "RPGMAKER_PROJECT_PATH": "/path/to/your/rpgmaker/project"
      }
    }
  }
}

（ソースからチェックアウトした場合は、代わりに "command": "node" と "args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"] を使用してください。）

利用可能なツール

全 128 ツールを分野別にまとめています。プロジェクトに書き込むツールは、オプションの dryRun 引数を受け付けます（ドライランプレビューを参照）。構造的に無効な書き込みを拒否するツールは、force も受け付けます（イベントの検証を参照）。

ツールリファレンス全体を展開

プロジェクトの指定

• get_project — サーバーが操作しているプロジェクト：パス、有効性、ゲームタイトル
• set_project — セッション中、サーバーの対象を別のプロジェクトディレクトリに変更します（再起動不要。RPGMAKER_PROJECT_PATH を上書きします）

アクター

• create_actor、update_actor、search_actors

職業

• create_class、update_class
• add_class_learning — レベルで習得するスキルを追加します（スキルを検証し、習得項目をレベル順に保ちます）
• set_class_param_curve — 8 つのパラメーター成長曲線のうち 1 つを置き換えます

スキル

• create_skill（完全に制御できます。occasion、hitType、speed、repeats、successRate、tpGain、必要な武器タイプ、message2、note など、Skills.json のすべてのフィールドに対応します。hitType は、魔法スキルでは魔法、それ以外のダメージでは物理、回復や味方対象では必中がデフォルトです）、update_skill、search_skills
• create_damage_skill、create_healing_skill、create_buff_skill、create_state_skill — よく使われるスキルタイプ向けの、自然言語で指定しやすいヘルパー

アイテムと装備

• create_item、update_item、search_items
• create_weapon、update_weapon
• create_armor、update_armor

ステート

• create_state、update_state

敵と敵グループ

• create_enemy、update_enemy、search_enemies
• create_troop、update_troop、search_troops — create_troop は、すべてのメンバーが既存の敵を参照していることを検証します
• build_troop_page — コンパクトなトリガー（when：turn [a, b]、enemyHpBelow [slot, pct]、actorHpBelow [actorId, pct]、switch、turnEnd — AND 条件）と span（battle / turn / moment）から、戦闘イベントページ { conditions, list, span } を構築します。12 フィールドの条件オブジェクトを手作業で作成する必要はありません。読み取り専用です
• add_troop_page — 他のページを再送信せずに、敵グループにページを追加（または position の位置に挿入）します。HP 条件が敵グループのメンバー数を超えるスロットを参照している場合は警告します

コモンイベント

• create_common_event、update_common_event
• call_common_event — コード 117 の呼び出しコマンドを構築し、対象が存在することを検証します

マップとマップツリー

• get_map（大きなマップでは includeData: false を指定すると、タイル配列を省略できます）、get_map_infos、get_map_dimensions、update_map
• get_map_region — マップ全体ではなく、タイル ID の範囲（x、y、width、height、layer）を読み取ります
• create_map — 次の ID を割り当て、空のマップを書き込み、ツリーに登録します
• delete_map — マップを削除し、その子を親に付け替えます
• update_map_tree — 事前の存在確認と循環ガードを行いながら、親の変更、並べ替え、名前変更、展開をまとめて実行します

マップイベント

• get_map_events、get_map_event、search_map_events
• create_map_event、update_map_event、delete_map_event
• add_event_command — イベントページに単一のコマンドを追加します
• set_map_tile — z レイヤーの (x, y) に単一の生タイル ID を設定します（オートタイル化なし）

イベントと NPC の使いやすさ

• create_npc — 1 回限りの「会話する NPC」：グラフィック、トリガー、text から作成した会話リスト（wrap を指定すると自動で折り返し可能）、または明示的な commands
• create_chest — 1 回限りの宝箱：2 ページのセルフスイッチの慣用パターン（アイテム／武器／防具／ゴールドを付与し、その後は二度と実行しません）
• create_transfer — 1 回限りのマップ移動。動作する慣用パターンのいずれかを使用します。固体の目印に向き合う（action_button）か、玄関マットを踏む（player_touch）方法です
• set_event_page — ページのグラフィックと動作（スプライト、トリガー、優先度、移動、フラグ）をその場でマージします

イベントコマンドビルダー

読み取り専用のビルダーで、エディターに忠実な EventCommand シーケンスを返します。insert_event_commands でコマンドリストに追加できます。

• 会話とフロー： build_show_text (101/401)、build_show_choices (102/402–404)、build_conditional_branch (111/411/412)、build_flow_command (ウェイト／終了／ラベル／ジャンプ)
• ゲーム状態： build_control_switch (121/123)、build_control_variable (122)、build_change_gold (125)、build_change_items (126–128)、build_change_party_member (129)
• 演出とトランジション： build_transfer_player (201)、build_play_audio (BGM/BGS/ME/SE)、build_screen_effect (フェード／色調変更／フラッシュ／シェイク)、build_picture (表示／消去)、build_character_effect (アニメーション／フキダシ)
• シーン： build_battle_processing (301)、build_shop_processing (302/605)、build_name_input (303)、build_change_actor (HP/MP/状態／回復／EXP／レベル、311–316)
• 戦闘（敵グループページ）： build_battle_command — 敵の出現 (335、非表示のメンバーを表示)、敵の状態変更 (333、1 スロットまたは敵グループ全体)、戦闘の中断 (340)
• 挿入： insert_event_commands — ビルドしたシーケンスをマップイベントページ（デフォルトの target）、コモンイベント本体、または敵グループのバトルイベントページに挿入して、検証します

移動ルート

• create_move_route — 名前付きパターン（patrol／approach／flee／wander／custom）から MoveRoute を作成します
• set_movement_route — 強制的な「移動ルートの設定」を挿入します（コード 205 + 505 の継続行）

プラグインコマンド

• scan_plugins — js/plugins/*.js の注釈を解析して、このプロジェクトに実際にあるプラグインコマンドを検出します（有効状態は js/plugins.js から取得）
• list_plugin_commands — 既知のプラグインコマンドを表示します（プロジェクトのスキャン結果を組み込みの許可リストにマージしたもの）
• create_plugin_command — 正規化された引数でコード 357 のプラグインコマンドを作成します

タイル、カタログ、ペイント

• describe_tile — 生のタイル ID をデコードします（シート、オートタイルの種類／形状、ジオメトリ）
• get_tile_catalog、find_tile — 人間が読みやすい名前とペイント可能なタイル ID を相互に解決します（find_tile は searchDescriptions を使ってカスタムシートのカタログ説明まで検索範囲を広げられます）
• paint_tiles、fill_area — オートタイル化を自動適用してペイントします
• paint_blueprint — ASCII ブループリントと凡例から領域全体を 1 回の書き込みでペイントします。グリフごとの [layer, tile] ペア、ID の代わりにカタログ名、垂直方向に連続する部分の最下部セルを壁側（面）タイプに変換する { wall: { top } } エントリ（上部 + 8 種類）、古い上層のクリアに対応します。レイヤーごとの個数と #／. の通行可否マップを返します
• place_object — 複数タイルにまたがる B/C オブジェクトを配置し、通行可能範囲を報告します

タイルセットのフラグ（通行可否／地形）

• get_tile_flags — タイルの通行可否／星／はしご／草むら／カウンター／ダメージ／地形タグをデコードします
• check_passability — セルのマップに応じたレイヤー別の判定を返します
• set_tile_flags — タイルのフラグを編集します（非破壊的にマージし、オートタイルの種類に属する 48 個すべての形状スロットに自動適用します）

アセット

• list_assets — 利用可能なアセットのベース名（キャラクター、顔グラフィック、タイルセット、画像、音声など）を列挙します

Web エクスポート

• export_web — itch.io または任意の静的ホスト向けに、不要ファイルを除いた HTML5 デプロイメントを作成します。対象は index.html、js/、css/、fonts/、icon/、data/*.json に加え、参照されている img/／audio/／movies/ 内のファイルのみです（データファイル内のすべての文字列、コアエンジンスクリプトとプラグイン内の文字列リテラル、プラグインの @default を参照として扱います。img/system/ は常に保持され、保持対象のトラックについてはすべての .ogg／.m4a 形式も保持されます）。Effekseer エフェクトも同じ方法で不要ファイルを除きます。effects/*.efkefc は、その名前が実際のエフェクト参照（アニメーションの effectName、イベント内のプラグインコマンドの引数、またはプラグインのパラメーター／文字列。その他のデータ文字列は対象外です。そのため、Poison という名前のステートやアニメーションがあっても Poison.efkefc は含まれません）である場合のみ保持され、そのファイル内に記載されたテクスチャ／モデルも一緒に保持されます。保持対象のエフェクトを解析できない場合は、effects/ 内のテクスチャとモデルをすべて保持します。エフェクトが参照されていない場合、effects/ フォルダーはエクスポートされません。フォルダーを outDir に書き出し、zip（デフォルト）が有効な場合は、アーカイブのルートに index.html を配置した <outDir>.zip も作成します。ファイル数／バイト数、保持／除外したアセットの数とパス（エフェクトを含む）、System.advanced の画面サイズ（itch の埋め込みサイズとして使用できます）、itch の 1000 ファイル／1 ファイルあたり 200 MB の制限を超えた場合の警告を返します。prune: false を指定するとすべてのアセットをコピーします。プラグインが実行時にアセット名を組み立てる場合に使用してください。プロジェクト内には何も書き込みません。outDir にプロジェクト自体や、コピー対象フォルダーの内部を指定することはできません。既存の空でない outDir は、以前の export_web の出力である場合にのみ置き換えられます。

ヘッドレスレンダリングとプレイテスト

プロジェクト独自の index.html をヘッドレス Chromium で起動し、バリデーターでは確認できないマップの見た目やプレイ時の動作を確認します。読み取り専用のため、プロジェクト内には何も書き込みません。out を指定しない場合、PNG は <os tmpdir>/rpgmaker-mz-mcp/renders/ に保存されます。inline: true を指定すると、ツールの応答で PNG も画像コンテンツとして返します。

• render_map — マップを1つスクリーンショットに撮影します。デフォルトでは、マップ全体を1枚の画像にレンダリングします（キャンバスはwidth×height×48 pxにリサイズされ、プレイヤーは非表示になり、カットシーンがマップを覆わないよう自動実行／並列イベントは停止され、マップ名のバナーは非表示になります）。代わりにxとyを渡すと、そのタイルを中心とする通常の816×624ゲーム画面が表示されます（プレイヤーは表示されます）。showEvents: falseを指定するとタイルのみが描画されます。switchesを指定すると、後のストーリー状態を確認できるよう、先にスイッチがオンになります。runEvents: trueを指定するとイベントが実行されます。PNGのパスとproblems（コンソールエラー、ページエラー、HTTP 404）が返されます。画像が見つからない場合は、エンジンがロードエラー画面で停止する代わりに、その画像は空白で描画され、problemsに記載されます。一辺が4800 pxを超えるマップでは、x／yビューが必要です。

• run_playtest — 1つのブラウザーセッションでステップスクリプトを実行します。各ステップはokと詳細を返し、実行は最初に失敗したステップで停止します。

  • load {mapId, x, y, direction?, party?, level?, gold?, switches?, variables?, selfSwitches?, items?, equip?, encounters?}は、その場所と指定状態で新しいゲームを開始します。encounters: trueを指定しない限り、ランダムエンカウントはオフのままです。
  • startEvent {eventId}はマップイベントを起動し、テキストが表示されるか、イベントが待機状態になるまで実行します。イベントでプレイヤーが転送された場合、このステップは新しいマップを待ち、transferredTo {mapId, x, y}として報告します。
  • advanceText {maxMs?}は、イベントが待機状態になるまでOKを押します。選択肢リストが開くか戦闘が始まると、その時点で停止し、表示されたメッセージ行（話者名を含む）と、開いている選択肢を返します。戦闘中に表示されたテキストは別途battleLinesとして返されるため、マップイベントの会話には混ざりません。
  • choose {index}は、0から始まるインデックスで選択肢を選びます。
  • walk {direction, steps?}はタイルごとに歩き、到着したタイルを報告します（to）。タイルへの進入が拒否された場合、プレイヤーのいるタイル（stoppedAt）と進入を拒否したタイル（blockedTile）の両方を報告します。これにより、見えない壁を見つけられます。タッチイベントが発生すると早めに停止します。そのイベントがドアの場合は転送が完了するまで待つため、toとtransferredToは新しいマップ上の位置になります。eventRunning／messageOpenはイベントがまだ実行中かどうかを示します（続けてadvanceTextを実行してください）。
  • press {button, times?}とwait {ms}。
  • autoBattle {troopId?, canEscape?, canLose?, maxMs?}は、すでに始まっている戦闘、またはtroopIdで指定した戦闘を自動AIで行い、maxMs（デフォルトは60秒）が経過すると終了します。victory／defeat／escaped、両陣営の最終HP、戦闘中のメッセージlines（敵グループの戦闘イベント、勝利テキスト）を報告します。戦闘は早送りされます。描画するフレームごとにエンジンが20フレーム実行されるため、戦闘は通常どおり（同じロジック、同じ確率）進行しますが、速度だけが上がります。10ターンのボス戦は約80秒ではなく約5秒で終わります。通常速度で戦闘を見るには、実行時にrealtime: trueを指定し、それに合わせてmaxMsを大きくしてください。速度が上がるのは戦闘のみです。マップ、歩行、会話は通常速度で進行します。
  • screenshot {name?}はPNGを保存します。
  • eval {script}は、"$gameSwitches.value(3)"など、ゲームページで評価されたJS式の値を返します。

  報告されるテキスト（lines、battleLines、choices、話者名）は、メッセージウィンドウに表示されるとおりです。\V[n]、\N[n]、\P[n]、\Gはその時点のゲーム状態の値に置き換えられ、\C[n]、\I[n]、\{、\.、\|などの制御文字は削除されるため、勝利テキストは92 EXP received!のように返されます。

  応答の末尾にはfinalState（シーン、マップ、位置、所持金、パーティ）とproblemsが含まれます。イベントやメッセージがまだ実行中の場合（たとえば、loadの直後にマップの自動実行カットシーンが始まった場合）、startEventとautoBattleは開始を拒否し、先にadvanceTextを実行するよう通知します。 要件。 どちらのツールにも playwright-core が必要です。これはオプションの依存関係であるため、インストールに失敗してもほかのツールに影響しません。この2つのツールは、修正方法を示すエラーを返すだけです。また、Chromium も必要です。ブラウザーはダウンロードされません。サーバーは、Playwright のキャッシュ（~/Library/Caches/ms-playwright、~/.cache/ms-playwright、%LOCALAPPDATA%\ms-playwright、または PLAYWRIGHT_BROWSERS_PATH）内にある最新の chrome-headless-shell（またはフル版 Chromium）を使用します。まだない場合は、npx playwright install chromium-headless-shell を実行するか、RPGMAKER_MCP_CHROMIUM に任意の Chrome／Chromium 実行ファイルを指定してください。各呼び出しでは、起動に約1～2秒かかり、それにスクリプトの実行時間が加わります。

長時間の実行。 長いカットシーンや realtime バトルを含む run_playtest スクリプトは、1分以上かかることがあります。これは、多くの MCP クライアントのデフォルトの待機時間を超えます（TypeScript SDK は60秒後に -32001 Request timed out を返して中断します）。クライアントが progressToken を送信すると、サーバーは各ステップの後と、長時間かかるステップの実行中は5秒ごとに進捗通知を送信します。そのため、resetTimeoutOnProgress を使用するクライアント（またはタイムアウトを長く設定したクライアント）は待機を続けられます。どちらにも対応していないクライアントの場合は、スクリプトを複数の短い実行に分割してください。

システムと用語

• get_system、get_game_title、update_game_title
• get_title_screen、update_title_screen — 背景レイヤー、BGM、「ゲームタイトルを描画」トグル
• get_variables、set_variable_name、get_switches、set_switch_name
• get_starting_position、update_starting_position
• get_party、set_party — 初期パーティ（set_party はすべてのアクター ID を検証します）
• get_terms、set_term — メニュー用語
• get_types、set_type_name — 属性／スキル／武器／防具／装備タイプ名のリスト
• set_currency_unit

一括作成

• batch_create — 1回の呼び出しと単一のファイル書き込みで、同じ種類のレコード（アクター、アイテム、武器、防具、スキル、敵、ステート、クラス）を複数作成します。ID は連番で割り当てられるため、レコードから同じバッチ内で先に作成された別のレコードを参照できます。対応する create_* ツールが受け付けないレコードのフィールドは、黙って破棄されず、警告として返されます

レコードの削除

• delete_record — データベースのレコード（アクター、クラス、スキル、アイテム、武器、防具、敵、トループ、ステート、コモンイベント）を1件削除します。スロットを null にするため、ほかの ID はずれません。削除後に参照先がなくなる箇所をすべて報告し、該当箇所がある場合は force: true が指定されない限り削除を拒否します
• reset_table — keep に指定した ID を除き、テーブル全体をクリアします（例：reset_table('skill', { keep: [1, 2] }) は RTP スキルを消去し、Attack／Guard は保持します）。保持するレコードの ID は変わらず、末尾の空スロットはトリミングされます。また、同様に参照先がなくなる箇所がある場合は拒否します

インデックスと検証

• list_names — テーブル（アクター、アイテム、スキル、マップ、敵など）の軽量な { id, name } インデックス
• get_database — 1つのテーブル（actors、classes、items、weapons、armors、skills、enemies、troops、states、common_events）のすべてのレコード、または id で指定した単一のレコード
• validate_event、validate_project — イベントコマンドの形式検証（読み取り専用）
• validate_references — ファイル間の ID 整合性監査（パーティ→アクター、場所移動→マップ、効果→ステート／スキル／コモンイベント、ドロップ→アイテム、「アイテムの増減」／「ショップの処理」／「バトルの処理」→アイテム／トループ、エンカウント→トループ、マップツリーの循環など）

ID の割り当て

• list_allocated_ids — プロジェクト内の JSON から取得した、すでに使用されているスイッチ／変数／コモンイベント ID。id を指定すると、その ID が参照されているすべての箇所を返します
• next_free_id — 手動で選ぶ代わりに、次の未割り当て ID を予約します（複数指定可）

入力検証

各ツールは、引数を Zod スキーマとして宣言します。MCP SDK の高レベルな McpServer を基盤とするサーバーは、ハンドラーの実行前に、このスキーマに照らして受信した引数を検証します。そのため、不正な呼び出しはディスクに不正なデータを書き込む代わりに、問題のあるフィールド名を示す明確な Input validation error とともに拒否されます。

イベントの検証（既定ではエラーをスロー）

イベントコマンドのリストは、既知のRPG Maker MZコマンドコードの表（101 テキストの表示、201 プレイヤーの場所移動、122 変数の操作など）と、それらのコマンドが構成するブロック構造に照らしてチェックされます。検出結果には2つのレベルがあり、レベルによって書き込みの扱いが決まります。

• 構造上の問題 — 既知のコマンドのパラメーター数が正しくない（条件分岐の条件タイプや変数の操作のオペランドタイプに応じて変わる数も含む）、コード0の終了マーカーでリストが終わっていない、parametersが配列ではない、ブロックが壊れている（「選択肢の表示」／条件分岐／ループが閉じられていない、分岐または閉じる行が孤立しているか、インデントが間違っている、「キャンセルの場合」分岐がない選択肢）、または通行不可のタイルにアクションボタンイベントが配置されている、といった問題です。これらはほとんどの場合バグであるため、イベント書き込みツールは書き込みを確定する前に、書き込み予定の結果を検証し、書き込みを拒否します。ツールはエラーを返し、ディスクには何も書き込まれません。force: trueを渡すと、それでも書き込めます（この引数は、書き込みを拒否できるツールに限り案内されています）。
• 参考情報 — 認識されないコマンドコード（プラグインコマンドの可能性があります）、長すぎるテキスト行、不明なアセットファイル名、「キャンセル」のルーティングと「キャンセルの場合」分岐が一致しない選択肢ブロック（到達不能なコードであり、データの破損ではありません）といった情報です。これらは正当なケースとして発生し得るため、処理をブロックすることはありません。通常のレスポンスにwarningsとして含まれます。

検証は確定の前に行われるため、拒否されるはずの書き込みをdryRunで実行した場合も、書き込みをプレビューするのではなく失敗します。

validate_event／validate_projectは引き続き読み取り専用の監査を行います。どちらのレベルの検出結果も、（各検出結果にseverityが含まれた状態で）報告し、何も変更しません。

テキスト幅：フォントを教える

長すぎるテキスト行の警告は、デフォルトでは文字数（1行あたり55文字、顔グラフィックが表示されている場合は38文字）で測定されます。標準のRTPフォントには適しており、設定は不要です。プロジェクトで別のフォントを使う場合、この推定には2つの方向で誤差が生じます。フォントが狭いと、余裕で収まる行でも警告が出ます。一方、フォントが広い、または大きいと、実際には切れている行でも警告が出ません（24pxの文字を38文字並べると912pxになり、616pxのウィンドウに収まりません）。比例フォントではグリフの幅に大きな差があり、ピリオドの幅が大文字の3分の1になることもあるため、どちらの問題も解決できる文字数の上限はありません。

プロジェクトのルートに**.rpgmaker-mcp.json**を置くと、推定値を実測値に置き換えられます。

{
  "text": {
    "lineBudget": { "noFace": 784, "withFace": 616 },
    "nameBudgetChars": 8,
    "charWidths": { "_default": 13, "a": 11.38, ".": 4.88, " ": 8.12 }
  }
}

• lineBudget — 顔グラフィックなし／ありの場合の、メッセージウィンドウの使用可能な幅です。charWidthsを指定した場合はピクセル単位、指定しない場合は文字数単位です。lineBudgetのみを指定すると、文字数の上限だけを上書きします。
• charWidths — 文字ごとの送り幅です。リストにない文字には_defaultが適用されます。エンジン自体から取得してください。実行中のゲームでWindow_Base.textWidth(c.repeat(40)) / 40を使うと、正確な値を取得できます。
• nameBudgetChars — \N[3]／\P[1]が表示される幅の想定値です。名前は実行時にプレイヤーが入力するため、デフォルトの名前ではなく、名前入力のmaxLength（通常は8）を基準にしてください。そうしないと、テスト時には収まっていた行が、長い名前によってはみ出すことがあります。デフォルトは0で、従来どおり名前のエスケープコードを無視します。

どのような場合でも、問題が起きても安全に動作します。ファイルがない場合、JSONが不正な場合、またはtextセクションの形式が不正な場合は、組み込みの推定値がそのまま使われるため、設定が壊れていても設定がない場合より悪くなることはありません。ファイルの更新日時が変わると再読み込みされ、その後の警告では実際の幅が報告されます（Show Text line is 650px but the message window fits 616px with a face shown）。

自動折り返し。 長すぎる行を手作業で直す代わりに、build_show_textまたはcreate_npcにwrap: trueを渡し、段落単位でテキストを記述できます。テキストは、警告の判定に使われる幅（デフォルトの推定値、または.rpgmaker-mcp.jsonの計測値）に合わせて単語単位で折り返されます（\C[n]などのエスケープコードは文字数に含まれず、分割もされません）。その後、必要な数の4行メッセージボックスに分割され、顔グラフィック／話者は同じものが使われます。wrap: true（または"soft"）は各エントリーを1つの段落として折り返します。"hard"は各エントリーと\nを強制改行として維持し、長すぎる行だけを折り返します。

参照の検証

validate_referencesは、上記のコマンド形式チェックとは別に、ファイル間のID整合性を監査します。データベース全体を調べ、存在しないものを参照する項目にフラグを立てます。たとえば、対応するアクターが存在しない初期パーティメンバー、存在しないマップを対象とする「場所移動」、存在しないステートを追加するスキル効果、不明なアイテムをドロップする敵、循環しているマップツリーの親などです。すべてのチェックはデフォルトで警告として扱われ、部分的に読み込まれたプロジェクトで誤検知しないよう対策されています。

レコードの削除とテーブルのリセット

新しい MZ プロジェクトには、アイコン、アニメーション、バトラーが RTP の素材を参照する、RTP 由来のデータベース行が含まれています。素材をすべて差し替える場合、まずデータベースを消去してから独自の内容を作成するのが自然なワークフローです。reset_table はその最初のステップで、delete_record は単一の行を削除します。

データベース配列では インデックス＝ID なので、どちらのツールもスロットをスプライスではなく null にします。番号が振り直されることはなく、残った参照が別のレコードを意図せず指すこともありません。reset_table は各 keep ID をそれぞれのインデックスに保持し、末尾の空スロットを切り詰めます（保持するものがないテーブルは [null] になります）。その後、create_* や batch_create で新しいレコードを作成すると、現在有効な ID のうち最も大きいものを基準に割り当てられます。

書き込みの前に、どちらのツールも、削除によって参照先がなくなる項目を特定するため、削除対象の行がある場合とない場合で validate_references の監査を実行し、削除によって新たに発生する問題だけを抽出します（すでに壊れていた参照は削除が原因とはみなしません）。スキル ID 1（Attack）、スキル ID 2（Guard）、ステート ID 1（Knockout）の削除も、エンジンでこれらの ID がハードコードされているため、必ず報告されます。参照先がなくなる項目がある場合、書き込みは拒否され、ディスクには何も書き込まれません。続行するには force: true を指定してください。また、消える項目と問題が発生する箇所をプレビューするには dryRun: true を指定します（dry-run では例外をスローせず、代わりに requiresForce を報告します）。スキャン対象は validate_references の対象範囲と同じであり、その範囲は coverage フィールドに記載されます。特性、アクターの初期装備、イベントページの条件、条件分岐のオペランド、スクリプト／プラグインコマンドはスキャンされません。

reset_table({ type: 'skill', keep: [1, 2], dryRun: true })   // what goes, what breaks
reset_table({ type: 'skill', keep: [1, 2], force: true })    // do it
batch_create({ type: 'skill', records: [...] })              // author the replacements

ID の割り当て

スイッチ、変数、コモンイベントの ID はすべて同じ名前空間を共有しており、RPG Maker では後からの編集で、すでに使用済みの ID を割り当てても止められません。この問題は気づかれないまま発生します。クラッシュもバリデーターの検出もなく、何時間もテストプレイした後で、ドアがなぜかすでに開いていることに気づく、といった具合です。

list_allocated_ids は、「何が使用済みか」をプロジェクトファイル自体から調べます。手作業で管理するリストではありません。RPG Maker のエディターで誰かが編集した時点で、そのようなリストはすぐに実態と食い違ってしまうためです。ID は、宣言されている（System.json のラベルや CommonEvents の行）場合、またはどこかで参照されている場合に、割り当て済みとみなされます。参照箇所には、イベントページの条件やコマンドリスト、コモンイベント、敵グループのページ、コモンイベントを使うスキル／アイテムの効果が含まれます。どちらも重要です。名前は付いているが未使用のスイッチは誰かが確保した ID であり、使用されているのに名前がない ID は、誰も記録していない確保済み ID です。より絞り込んで「スイッチ 23 は実際にどこで使われているか。変更する前に知りたい」と調べるには、id を渡してください。

next_free_id は、すでに割り当てられているすべての ID より大きい、次の未割り当て ID（または複数の ID）を返します。デフォルトでは、最大 ID より小さい空き ID はそのままにします（空き ID は、メモに記載されているものの、まだ書き込まれていない ID であることもよくあります）。意図的に整理する場合は reuseGaps: true を指定すると、空き ID を再利用します。このツールは読み取り専用です。ID を提案するだけで書き込みは行わないため、次に編集する人にも割り当てがわかるよう、set_switch_name／set_variable_name で名前を付けてください。この 2 つのツールは、ID が System.json の名前リストの末尾を超えている場合、リストを拡張します。そのため、next_free_id が返した ID には、エディターを開かずにいつでも名前を付けられます。

コマンドバリデーターと同様、使用状況のスキャンは網羅的ではなく、対象を選定したものです。スイッチ／変数 ID を持つコマンド（スイッチの操作、変数の操作、条件分岐、プレイヤーの場所移動やゴールド／アイテム／HP／MP／経験値／レベルの変更における「変数で指定」する形式など）を対象とし、各レポートにはスキャンしたコマンドコードが記載されます。Script（355）またはプラグインコマンド（357）からのみ使用されている ID は、未使用として表示されます。

ドライランプレビュー

プロジェクトに書き込むすべてのツールは、オプションの dryRun 引数を受け取ります。dryRun: true の場合、ツールは書き込む内容を計算し、ファイルには一切触れずに差分を返します。

{
  "dryRun": true,
  "wouldChange": [
    {
      "file": "System.json",
      "changed": true,
      "diff": {
        "changes": [{ "path": "gameTitle", "from": "Old Title", "to": "New Title" }],
        "truncated": false
      }
    }
  ],
  "wouldReturn": { "...": "what the tool would have returned, warnings included" }
}

wouldReturn にはツールが返すはずだったレスポンスが格納されるため、ドライランでは差分だけでなく、書き込み時に報告される検証警告もプレビューできます。

すべての書き込みは単一の処理箇所を経由します。この処理箇所では、変更がない書き込みをスキップし、ディスク上の JSON をエディターのコンパクトな単一行形式に保ちます。ファイルの削除（例：delete_map）も同じドライランの仕組みを利用します。

書き込み結果の簡潔なエコー

レコード全体をエコーする書き込みツールは、そのコストを常に負担する唯一の呼び出し元である AI アシスタントに負担をかけます。コンテキストは貴重なリソースだからです。そのため、コマンドリストやマップのイベントをそのまま返すツールは、デフォルトで要約を返します。

tool	echoes
update_map, resize_map	タイルの data と events を除いたマップ、および dataTileCount / eventCount
update_map_event, set_event_page, add_event_command	イベントの識別情報 + ページごとの trigger / priorityType / moveType / グラフィック / listLength
insert_event_commands	listLength + listCodes — パラメーターを除いた、結果のコマンドコード
create_common_event, update_common_event	識別情報、トリガーの設定、listLength + listCodes
create_troop, update_troop, add_troop_page	識別情報、メンバー、ページごとの listLength

ルールは、アサートに使う情報は残し、読み直すだけの情報は省くことです。コマンドコードは、挿入が指定どおりに行われたことを確認する手段（「302 は 101 が 2 つ続いた後にまだあるか」）なので残します。コマンドパラメーターは、たった今書き込んだ内容なので省きます。

これらの呼び出しでは verbose: true を指定すると、以前のようにレコード全体が返されます。または、get_map / get_map_event / get_database で読み戻してください。warnings は要約後も常に残り、ドライランの wouldReturn も同じ方法で要約されるため、プレビューと実際の呼び出しで同じ形式の結果が返されます。

実際の制作セッションから6回の呼び出しを測定したところ、**115,080 → 3,672 文字（-97%）**でした。マップの BGM を設定する単一の update_map が、46,846 文字分の会話を呼び出し元にエコーしていました。

カスタムタイルセットカタログのスキル

デフォルトのタイルセットは、最初からカタログ化されています。RPG Maker の .txt 名称サイドカーファイルが隣にある非デフォルトのシート（img/tilesets/<Sheet>.txt。タイルごとに Name|日本語名 を1行記述。商用 DLC パックにも含まれています）も、自動的にカタログ化されます。その名称は source: 'sidecar' として返され、カタログファイルは不要です。タイルごとの優先順位は、人が検証した（manual）data/tilecatalog/ のエントリー > サイドカー > ビジョンドラフトです。サイドカーのないカスタム（非 RTP）タイルセットの場合、同梱の Claude スキル .claude/skills/tileset-catalog/ が各シートをラベル付きのサンプルに切り分け、Claude に画像を見て名称を付けさせ、プロジェクト固有のバージョン管理されたカタログを data/tilecatalog/ に書き込みます。これ以降は、そのシートの名称も find_tile / get_tile_catalog で検索できます。これらのドラフトには各タイルがどのように見えるかも記録されるため、機械生成の名称が短すぎて検索しづらい場合は、find_tile の searchDescriptions: true でその説明文も検索できます。このスキルには依存関係不要の PNG コーデックとエンジンと完全に一致するタイルのジオメトリが同梱されているため、Node が動作する環境ならどこでも実行できます。

プロンプトの例

設定が完了したら、自然言語でプロジェクトを操作できます。

• 「敵1体に a.mat * 4 - b.mdf * 2 のダメージを与える、消費MPが15の炎属性スキル『Fireball』を作成して。」
• 「ワールドマップの下に、30×25の新しい町のマップを作成して。タイルセットは Outside を使って。」
• 「マップ3の (4, 4) を左上とする10×8の長方形に草地を敷き、自動で境界を付けて。」
• 「マップ2の (8, 5) に、話しかけると『止まれ！誰だ？』と言う『Guard』という名前の NPC を配置して。」
• 「タイルセット1の水タイルを通行不可にして、地形タグ1を設定して。」
• 「リリース前に、プロジェクト内の壊れた参照を確認して。」

開発

npm run build         # Compile TypeScript to dist/
npm run typecheck     # Type-check without emitting (tsc --noEmit)
npm run dev           # Compile in watch mode
npm run lint          # ESLint
npm run lint:fix      # ESLint with autofix
npm run format        # Format with Prettier
npm run format:check  # Check formatting (used in CI)
npm test              # Vitest
npm run sync:tools    # Re-stamp the tool count into the README + SVGs (see below)
npm run sync:version  # Re-stamp package.json's version into the packaging manifests
npm run bundle:mcpb   # Build the one-click Claude Desktop bundle (rpgmaker-mz-mcp.mcpb)

開発中は、tsxを使ってソースからサーバーを実行すれば、ビルドを完全に省略できます。MCP クライアントの command を node_modules/.bin/tsx に設定し、引数に src/index.ts を指定してください。tsx は型チェックを行わないため、コミット前に lint やテストとあわせて npm run typecheck を実行してください。

CI では、プッシュとプルリクエストのたびに lint、フォーマットチェック、ツール数の同期チェック、テスト、ビルドを実行します（.github/workflows/ci.yml を参照）。

ツール数を同期する

表示しているツール数は、README の文章とバッジ、および assets/ 内の 2 つの SVG など、人の目に触れるいくつかの箇所に記載されています。npm run sync:tools は src/tools/ から実際のツール数を数えて、すべての箇所に反映するため、ツールを追加した後の数の更新は 1 つのコマンドで完了します。npm run sync:tools:check（CI で実行）は、いずれかの箇所が古い場合に失敗します。

リリース

バージョンの正式な参照元は package.json です。npm run sync:version を実行すると、プラグインマニフェスト（.claude-plugin/plugin.json）、MCP レジストリのメタデータ（server.json）、MCPB マニフェスト（mcpb/manifest.json）にバージョンが反映されます。CI と prepublishOnly は、これらに食い違いがあると失敗します。リリース手順は次のとおりです。

npm version minor --no-git-tag-version   # or patch/major — bumps package.json only
npm run sync:version                     # stamp it into the other three manifests
git commit -am vX.Y.Z                    # one commit, with every manifest already correct
git tag vX.Y.Z                           # tag it afterwards, so nothing rewrites it
git push && git push origin vX.Y.Z

npm publish                 # publish to npm (runs the full gate via prepublishOnly)
mcp-publisher publish       # update the MCP registry listing (server.json; login: mcp-publisher login github)
npm run bundle:mcpb         # build rpgmaker-mz-mcp.mcpb
gh release create vX.Y.Z rpgmaker-mz-mcp.mcpb --title vX.Y.Z --notes "..."   # publish the GitHub release + attach the bundle

Claude Code プラグインは別途公開する必要はありません。ユーザーのインストールはこのリポジトリから更新されます（プラグインは npx rpgmaker-mz-mcp@latest 経由で npm パッケージを実行するため、新しいツールをリリースするには npm のバージョンを上げます）。

タグ付けは最後に行い、タグを付けたコミットは絶対に amend しないでください。 npm version を単独で実行すると、sync:version が他のマニフェストにバージョンを反映する前に、コミットとタグの両方が作成されます。そのため、以前の手順では後から amend していましたが、タグは amend 前のコミットを指したままになり、マニフェストが古く、ブランチからも外れた状態になっていました。--no-git-tag-version を使えば、この問題をすべて回避できます。まずコミットを 1 つ作り、その後にタグを付けます。タグは名前を指定してプッシュしてください（ここでは --follow-tags は間違えやすい方法です）。また、gh release create を省略しないでください。それ以前の手順では GitHub リリースは作成されません。

プロジェクト構成

rpgmaker-mz-mcp/
├── src/
│   ├── index.ts              # McpServer bootstrap: registers every tool, dispatch + dry-run
│   ├── registry.ts           # ToolDefinition shape + shared dryRun schema
│   ├── tools/                # One module per area (actors, items, skills, maps, battle,
│   │                         #   classes, states, common events, moves, plugins, tiles,
│   │                         #   catalog, paint, objects, tilesets, system, assets,
│   │                         #   event-command builders, event pages, list, validation)
│   ├── events/               # Pure event-command builders (no I/O)
│   ├── tiles/                # Tile subsystem: codec, autotile solver, paint core,
│   │                         #   flag codec, and the semantic catalog
│   ├── playtest/             # Headless engine driver: Chromium discovery, static server,
│   │                         #   render_map + run_playtest (optional playwright-core)
│   ├── validation/           # Known-command tables + event/move/plugin/reference validators
│   └── utils/                # File I/O, the commit choke point, and RPG Maker MZ types
├── test/                     # Vitest suite
├── scripts/
│   └── sync-tool-count.mjs   # Re-stamps the tool count into the README + SVGs
├── assets/                   # Banner + architecture SVGs
├── .claude/skills/
│   └── tileset-catalog/      # Vision catalog-bootstrap skill for custom tilesets
├── dist/                     # Compiled JavaScript (gitignored)
└── README.md

安全性とベストプラクティス

1. このサーバーの使用中は RPG Maker MZ エディターを閉じてください。このサーバーは JSON ファイルに直接書き込み、エディターは保存時に変更を上書きする可能性があります。
2. プロジェクトには バージョン管理を使用してください。ドライランのプレビューと検証を組み合わせることで、git が安全策になります（サーバーは自動バックアップを作成しません）。
3. 破壊的な編集を適用する前に、dryRun: true を指定して プレビューしてください。
4. 大きな変更を行った後は ゲーム内でテストしてください。

制限事項

• JSON ファイルに直接書き込むため、競合を避けるにはエディターを閉じる必要があります。
• プラグインコマンドは、プロジェクトに実際に含まれているプラグインに照らして検証されます（scan_plugins はそれらの @command／@arg アノテーションを解析します）。該当するものがない場合は、小規模な組み込み許可リストが使われます。RPG Maker MZ には「必須の引数」を示すアノテーションがないため、スキャンされた引数は不明な名前のみがチェックされ、欠落している引数はチェックされません。アノテーションブロックのないプラグインは、チェックされずにそのまま通過します。
• アニメーション（Animations.json、Effekseer ベース）は、このサーバーでは編集されません。

謝辞

このプロジェクトは、k4zuki0539/-rpgmaker-mz-mcp（MIT）のフォークとして始まりました。このプロジェクトから、CRUD の基本的な構成を提供していただきました。その後、元の出発点を大きく超えて、バニラのレベルデザインとゲームロジックの作成全般に対応するまでに成長し（機能を参照）、現在は独立したプロジェクトとして保守されています。基盤を築いてくださった原作者に感謝します。

ライセンス

MIT

リソース

• RPG Maker MZ 公式サイト
• Model Context Protocol ドキュメント
• RPG Maker MZ データベース構造