Rpgmakermvultimate Mcp

Model Context Protocol サーバーです。18 個の統合ツールを通じて、AI エージェントがディスク上の実際の RPG Maker MV プロジェクトを調査、編集できます。壊れた参照やスイッチ条件を見つけ、MV 互換のコマンドでイベントを作成し、繰り返し実行できるプレイテストを行います。生成されたデータは、ゲームのタイルセットやプラグインで引き続き検証する必要があります。

通常は不足しがちな、次の 3 つの機能を備えています。

⚡ クイックスタート

Node.js 20.19.0 以降をインストールし、エージェントにプロジェクトファイルを編集させる前に MV エディターを閉じてください。まずはプロジェクトのコピーを使ってください。

コンテナやディレクトリのホスティングについては、Docker と Glama のビルド設定を参照してください。

Windows x64 MCPB バンドル： 対応する MCPB クライアント向けに、v5.21.0 をダウンロードしてください。バンドルの要件と検証を参照してください。以下の npm セットアップは、対応するすべてのオペレーティングシステムで利用できます。

プロジェクトは itch.io と Smithery でも確認できます。

サーバーを追加する前に環境を確認してください（Windows の PowerShell）：

npx.cmd -y rpgmaker-mv-mcp --doctor "C:/path/to/your/RPGMakerMV/project"

coreReady: true は、Node と System データのチェックに合格したことを示します。headlessReady: true は、さらに Playwright と Chromium が利用可能であることを示します。このチェックではブラウザーは起動せず、アセットやプラグインの状態も保証しません。ブリッジの警告があっても、オフラインでの問い合わせは妨げられません。Chromium が見つからない場合は、npx.cmd playwright install chromium-headless-shell を実行するか、Chrome の実行ファイルを RPGMAKER_MCP_CHROMIUM に設定してください。

1 — MCP クライアントに追加します。 クローンは不要です。このパッケージには実行可能ファイルが含まれています。

設定

{
  "mcpServers": {
    "rpgmaker-mv": {
      "command": "npx",
      "args": ["-y", "rpgmaker-mv-mcp"],
      "env": {
        "RPGMAKER_PROJECT_PATH": "C:/path/to/your/RPGMakerMV/project"
      }
    }
  }
}

# Claude Code, user scope
claude mcp add rpgmaker --scope user \
  --env RPGMAKER_PROJECT_PATH="C:/path/to/project" \
  -- npx -y rpgmaker-mv-mcp

# From source
git clone https://github.com/DiegoLopez0208/RpgMakerMVUltimate-MCP
cd RpgMakerMVUltimate-MCP
npm install && npm run build
RPGMAKER_PROJECT_PATH=/path/to/your/project npm start

2 — プロジェクトを指定します。 RPGMAKER_PROJECT_PATH は data/、js/、index.html を含むフォルダーです。サーバーはこの指定がなくても起動します。必要に応じて、実行時に set_project_path を呼び出してください。

3 — まずエージェントに中を確認させます。

get_project_context { detail: "full" }        → what exists, with real IDs
analyze_project     { view: "overview" }      → health, counts, unreachable maps

Claude Desktop、Claude Code、opencode、および MCP 互換クライアントで動作します。

Codex CLI の場合は、codex mcp add rpgmaker --env RPGMAKER_PROJECT_PATH=C:/path/to/project -- npx -y rpgmaker-mv-mcp を使用してください。npx を起動できない Windows クライアントでは、コマンドに cmd を指定し、引数に ["/c", "npx", "-y", "rpgmaker-mv-mcp"] を指定してください。クライアントを再起動してから、最初に試す3つのレシピをお試しください。

🧭 できること

flowchart LR
    A["🤖 Agent"] -->|"generate_map · manage_map_event"| B["📁 Project on disk"]
    B -->|"validate · balance · metrics"| A
    B -->|"playtest"| C["🎮 Running game"]
    C -->|"exceptions · position · screenshots"| A
    A -->|"reload_map"| C

このループの後半部分をブリッジが担います。ブリッジがなければ、エージェントはファイルを書き出して、うまくいくことを期待するだけでした。

🗺️ マップ生成

どちらも generate_map で利用できる2つの方法があります。プロジェクトで RTP アートを使用しているかどうかで選んでください。

知識を活用する方法

{ "mode": "procedural", "theme": "town", "name": "Riverbend", "width": 40, "height": 30 }

対応するテンプレートがあるテーマ — 町、村、ダンジョン、屋内、城、ワールドなど — では、タイルのノイズを描画する代わりに実際のマップを複製します。対応するテンプレートがないテーマ（ビーチ、沼地、砂漠…）では、パーリンノイズによる地形、BSP ダンジョン、セルオートマトン洞窟に切り替わります。戦闘テーマでは既存の敵グループからランダムエンカウントを自動設定し、町や村では双方向ワープ付きで、入ることのできる家の屋内マップを自動作成します。

テーマ · forest town village castle dungeon cave beach desert swamp ruins interior snow harbor volcano sewer fortress magic_forest magic_interior space_interior space_exterior world

その他のモード：blank（空のキャンバス）、themed（シンプルなレイアウト）、template（同梱マップを1つ指定）、batch（一度に複数生成）、duplicate（既存のマップをコピー）。

タイルセットに依存しない方法

同梱テンプレートは生の MV マップ JSON であり、そのタイル ID は RTP シートでのみ意味を持ちます。タイルセットを変更すると、マップはノイズのようになります。semantic では、最後の段階までレイアウトを抽象的なままに保ちます。

manage_system { action: "mine_templates" }               # learn from THIS project
generate_map  { mode: "semantic", tilesetId: 5, rooms: 6, seed: 42 }

• マイニングでは、作成済みのすべてのマップを読み込み、意味的なレイアウト（地面／壁／水／オブジェクト／扉。複数タイルのオブジェクトは分割せず保持）、各役割に対してプロジェクトで使用する具体的なタイルを示すタイルセットプロファイル、トークンの隣接数を導出します。プロジェクトは変更されず、すべて .mcp-cache/ に保存されます。
• 生成では、まずミッション（入口 → 鍵 → 鍵のかかった扉 → 宝物 → ボス → 出口と、脇道の部屋）を、辺が唯一の通過経路となるグラフとして構築し、その後に描画します。ロックは辺にあり、鍵はその手前の入口側に配置されるため、マップは構造上、必ず攻略可能です。オートタイルの形状は、セルごとに推測するのではなく、完成した近傍に基づいて最後に再計算されます。
• 結果には、各ミッション上の役割のセルを示す markers が含まれます。ここが manage_map_event でイベントを配置する場所です。
• マイニング済みの templateId（例："mined-3"）を渡すと、自作のマップを別のタイルセットに再マテリアライズできます。

playtest 単体では、起動後は何も返ってこない、いわゆるファイア・アンド・フォーゲットです。ブリッジがフィードバックループを閉じます。

manage_system { action: "install_bridge_plugin" }   # once per project
manage_system { action: "bridge_start" }            # opens ws://127.0.0.1:32123
manage_system { action: "playtest" }                # the game connects on its own
manage_system { action: "bridge_telemetry", types: ["exception", "log"] }

sequenceDiagram
    participant A as 🤖 Agent
    participant S as 🖥️ MCP server
    participant G as 🎮 Game (nwjs)
    A->>S: edit_map
    S->>S: atomic write to Map002.json
    A->>S: bridge_command reload_map
    S->>G: reload_map
    G->>G: reserveTransfer + _needsMapReload
    G-->>S: reload_complete
    A->>S: take_screenshot
    S->>G: capture_screenshot
    G-->>S: PNG in base64
    S-->>A: path for analyze_image
    A->>S: record_video start / stop
    S->>G: MediaRecorder on the game canvas
    G-->>S: WebM in base64
    S-->>A: path for video evidence

• 📡 テレメトリー — スタックトレース付きの例外、console.error／warn、シーンの変更、プレイヤーの位置、実行中のイベントコマンド（停止したイベントを特定できます）、FPS、ヒープ。peek を渡さない限り、フレームは読み取ると消費されます。
• ♻️ ホットリロード — reload_map は現在の MapXXX.json を再読み込みし、パーティーの状態を失わずにシーンを再構築します。Spriteset_Map を手動で再構築するのではなく、エンジン独自のリロード機構である _needsMapReload を使って、プレイヤー自身の位置への移動を予約します。reload_database はデータファイルを1つ再読み込みします。System.json と Tilesets.json は新たなプレイテストが必要なため、説明を返して処理を拒否します。
• 📸 スクリーンショット — take_screenshot { name: "collision-proof" } は MCP プラグイン経由で実行中のプレイテストを撮影し、タイムスタンプ付きの PNG を .mcp-cache/screenshots/ に保存して、確認や QA の証拠として使えるパスを返します。シェルのスクリーンショットコマンドは使いません。manage_system { action: "bridge_screenshot" } は引き続き互換性エイリアスとして使えます。
• 🎥 動画による証拠 — record_video { action: "start", name: "npc-dialogue" } は実行中のゲームキャンバスの無音 WebM キャプチャを開始します。record_video { action: "stop" } は動画を .mcp-cache/recordings/ に保存し、パスを返します。エージェントは、許可リストにある interact コマンドと固定ボタン入力の press_button を使って、再現可能なシーンを設定できます。任意のスクリプトや eval コマンドは引き続き使えません。

🔒 セキュリティ

ゲームが NW.js 上で実行されており、かつ test 引数を付けて起動された場合を除き、プラグインはほかの処理が実行される前に戻ります。プレイヤーがダブルクリックして起動するリリース版ビルドでは、ソケットコードにも require('fs') にも到達しません。

Utils.isOptionValid のように argv[0] だけを見るのではなく、すべての引数を確認します。これは、playtest が最初にプロジェクトパスを渡すためです。そのため、リリース版ビルドを文字どおりの test 引数を付けて意図的に起動するとガードを通過しますが、ハンドシェイクファイルが見つからず、接続も行われません。

サーバーは 127.0.0.1 のみで待ち受け、ブラウザーの Origin を伴うアップグレードをすべて拒否します（クロスサイト WebSocket ハイジャック対策）。また、5秒以内に .mcp-bridge.json のセッショントークンを定数時間で比較して照合する必要があり、照合できない場合は接続が切断されます。

コマンドは固定の許可リストに限定されており、eval プリミティブはありません。

analyze_project は読み取り専用で、完全にオフラインで動作します。プロジェクト全体を一度モデル化するため、エージェントは自分で作成していないゲームについても推論できます。

検索では searchMode: "lexical"、complete、indexedFiles、skippedFiles、warnings が返されます。complete: false は、一部のデータを読み取れなかったことを意味します。ゲームに一致するコンテンツがないという意味ではありません。結果が空の場合は noResultsReason が含まれます。プロジェクト内に実際に存在する名前やフレーズを使ってください。herrero は Blacksmith に翻訳されません。日本語を含む Unicode の名前に対応しています。存在しない ID をデータベースに問い合わせると null が返される場合があります。その ID を使う前に確認してください。

インデックス、概要、検証、グラフ、使用状況、説明、リファクタリングでも、入力が不完全であることが報告されます。読み取れないファイルは検証エラーとして表示されます。

オフラインでのマップ確認

• query_map { view: "ascii", mapId } — イベントマーカー付きの文字グリッドとしてマップを描画します。レイアウトを確認して座標を選ぶ最も手軽な方法です。
• query_map { view: "validate", mapId } — 1つのマップを検査し、無効なタイル ID、壊れた転送、欠落しているイベント終端を検出します。

ツール

このサーバーは統合された18個のツールを公開します。旧式のエイリアスは任意で使用できます。

イベントロジックを組み立てる場合は、build_event_commands の後に dryRun:true を指定して insert_event_commands を実行してください。プレビューには、変更前と変更後のコマンド一覧が正確に表示されます。 サポートされている種類、ネストのルール、MV 固有の違い、検証については、イベントコマンドの作成を参照してください。

• アトミックです。 すべての書き込みは一時ファイルに対して行い、対象ファイルと置き換えるため、呼び出しが中断されても JSON が中途半端に書き込まれることはありません。
• バックアップされます。 .mcp-backups/ にタイムスタンプ付きのローテーションバックアップを保存します（最新 N 件。RPGMV_BACKUP_KEEP、デフォルトは 10）。バックアップに失敗した場合、置き換えは中止されます。書き込みには一意の一時ファイルとファイルごとの排他ロックを使用します。データの読み取り後に変更が検出された場合、書き込みは拒否されます。エディターを終了してください。エディターは MCP のロックを無視するため、複数ファイルの操作はトランザクションではありません。
• プレビューできます。 変更を行うツールに dryRun: true を渡すと、ディスクに触れずに、書き込まれる内容を正確に確認できます。

⚠️ エージェントの作業中は RPG Maker エディターを終了してください。 エディターはプロジェクトをメモリー上に保持しており、保存時に変更を上書きします。

⚙️ 設定

# OpenAI
VISION_API_URL=https://api.openai.com VISION_API_KEY=sk-... VISION_MODEL=gpt-4o npm start
# Ollama (local, no key)
VISION_API_URL=http://localhost:11434 VISION_MODEL=llava npm start

🎓 エージェントスキル

ポータブルな エージェントスキル を使うと、どのモデルでもクラッシュを防ぐワークフローを実行できます。generate_map でマップを作成し、manage_map_event プリセットでコンテンツを追加し、タイルを手作業で描いたり ID を推測したりしないようにします。skill/rpgmaker-mv-mcp/SKILL.md にあります。

# Claude Code / Claude.ai
npx degit DiegoLopez0208/RpgMakerMVUltimate-MCP/skill/rpgmaker-mv-mcp ~/.claude/skills/rpgmaker-mv-mcp
# opencode
npx degit DiegoLopez0208/RpgMakerMVUltimate-MCP/skill/rpgmaker-mv-mcp ~/.opencode/skills/rpgmaker-mv-mcp

awesome-claude-skills にも掲載されています。

🚧 既知の制限とロードマップ

• RTP テンプレートを使う方式では、装飾の意味付けはベストエフォートです。まれに、複数タイルのオブジェクトが単一タイルとして配置されることがあります。抽出方式では、複数タイルのプロップはひとまとまりのまま保持されます。
• 町やダンジョンのレイアウトは継続的に改善しています。今後の予定：中央広場や井戸を目印として配置する、道路に面した家を列状に並べる、柵や庭を追加する、道路網を充実させる、部屋のバリエーションを増やす。
• mode: "semantic" は現在、ダンジョン型のミッションを生成します。次は町やオープンワールドのミッション文法への対応と、抽出した隣接数を説明だけでなく「装飾」に活用することです。
• balance はカテゴリ内で同種のもの同士を比較するため、ボスがランダムエンカウントより外れ値に見えるのは当然です。判定結果ではなく、フラグを確認してください。
• ブリッジは Windows／nwjs でのプレイテスト専用で、プロジェクトへのプラグインのインストールが必要です。
• ビジョン AI には、ご自身のエンドポイントが必要です。

🛠️ 開発

npm install
npm run build      # tsc compile (+ copies knowledge/ into dist/)
npm test           # vitest
npm run typecheck
npm run dev        # tsx watch mode

💬 フィードバック

積極的に開発しており、フィードバックを歓迎します。バグ報告、奇妙なマップ、足りないツール、アイデアなどをお寄せください。GitHub Issue を作成し、エージェントに依頼した内容と実際に得られた結果をお知らせください。エクスポートしたマップ JSON やスクリーンショットがあると、とても参考になります。