RPG Maker MV Ultimate MCP

🎮 RPG Maker MV Copilot MCP

Find why an MV event never fires — then verify the fix in the real engine

30-second silent workflow: a visual replay of verified MCP calls and a real MV 1.6.1 playtest. Inspect the evidence .

[Quick start](#-quick-start) · [First useful result](docs/first-result.md) · [Map generation](#️-map-generation) · [Live bridge](#-the-live-bridge) · [Intelligence](#-project-intelligence) · [Tools](#tools)

A Model Context Protocol server that lets an AI agent inspect and edit a real RPG Maker MV project on disk through 18 consolidated tools. Find broken references and switch conditions, build events with MV-compatible commands, and run repeatable playtests. Generated data still needs validation in your game's tilesets and plugins.

It does three things that are usually missing:

⚡ Quick start

Install Node.js 20.19.0 or newer, and close the MV editor before asking the agent to edit project files. Start with a copy of your project.

For containers and directory hosting, see Docker and Glama build configuration.

Windows x64 MCPB bundle: download v5.21.0 for a compatible MCPB client. See bundle requirements and verification. The npm setup below works across supported operating systems.

Find the project on itch.io and Smithery.

Check the environment before adding the server (PowerShell on Windows):

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

coreReady: true means Node and System data checks pass. headlessReady: true additionally means Playwright and Chromium are available. The check does not start a browser or certify assets/plugins. Bridge warnings do not block offline queries. Missing Chromium: run npx.cmd playwright install chromium-headless-shell, or set RPGMAKER_MCP_CHROMIUM to your Chrome executable.

1 — Add it to your MCP client. No clone needed; the package ships an executable.

Configuration

{

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

Claude Code one-liner, and running from source

# 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

MCP clients load tool definitions once at startup, so restart the client after adding or upgrading the server.

2 — Point it at a project. RPGMAKER_PROJECT_PATH is the folder containing data/, js/ and index.html. The server starts without it; call set_project_path at runtime instead if you prefer.

3 — Let the agent look around first.

get_project_context { detail: "full" }        → what exists, with real IDs

analyze_project { view: "overview" } → health, counts, unreachable maps

Works with Claude Desktop, Claude Code, opencode, and any MCP-compatible client.

For Codex CLI, use codex mcp add rpgmaker --env RPGMAKER_PROJECT_PATH=C:/path/to/project -- npx -y rpgmaker-mv-mcp. In Windows clients that cannot launch npx, use the command cmd with arguments ["/c", "npx", "-y", "rpgmaker-mv-mcp"]. Restart the client, then try the three first-result recipes.

🧭 What it does

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

The bottom half of that loop is what the bridge adds. Before it, the agent wrote files and hoped.

🗺️ Map generation

Two paths, both behind generate_map. Pick by whether your project uses RTP art.

The knowledge-driven path

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

Themes with a matching template — town, village, dungeon, interior, castle, world and more — clone a real map instead of painting tile noise. Themes without one (beach, swamp, desert…) fall back to Perlin terrain, BSP dungeons and cellular caves. Combat themes auto-wire random encounters from your existing troops; town and village auto-create enterable house interiors with two-way warps.

Themes · 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

Other modes: blank (empty canvas), themed (simple layout), template (one specific bundled map), batch (many at once), duplicate (copy an existing map).

The tileset-independent path

The bundled templates are raw MV map JSON, so their tile IDs only mean anything on RTP sheets. Change the tileset and the map turns to noise. semantic keeps the layout abstract until the last moment:

manage_system { action: "mine_templates" }               # learn from THIS project

generate_map { mode: "semantic", tilesetId: 5, rooms: 6, seed: 42 }

• Mining reads every map you already made and derives semantic layouts (ground / wall / water / prop / door, multi-tile props kept whole), a tileset profile naming the concrete tile your project uses for each role, and token adjacency counts. Nothing in the project is modified — everything lands in .mcp-cache/.
• Generating builds the mission first — entrance → key → locked door → treasure → boss → exit, plus side rooms — as a graph whose edges are the only ways through, *then* paints it. Because the lock is an edge and the key sits on the entrance side of it, the map is solvable by construction. Autotile shapes are recomputed at the end from the finished neighbourhood, never guessed cell by cell.
• The result includes markers naming the cell of every mission role, which is where to put events with manage_map_event.
• Pass a mined templateId (e.g. "mined-3") to re-materialise one of your own maps onto a different tileset.

🔌 The live bridge

playtest on its own is fire-and-forget: the game opens and nothing comes back. The bridge closes the loop.

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

• 📡 Telemetry — exceptions with stack traces, console.error/warn, scene changes, player position, *which event command is executing* (so a hung event can be pinpointed), FPS and heap. Frames are consumed as you read them unless you pass peek.
• ♻️ Hot reload — reload_map re-reads the current MapXXX.json and rebuilds the scene without losing party state: it reserves a transfer to the player's own position with _needsMapReload, the engine's own reload seam, rather than rebuilding Spriteset_Map by hand. reload_database re-reads one data file; System.json and Tilesets.json need a fresh playtest and are refused with an explanation.
• 📸 Screenshots — take_screenshot { name: "collision-proof" } captures the live playtest through the MCP plugin, saves a timestamped PNG under .mcp-cache/screenshots/, and returns its path for inspection or QA evidence. No shell screenshot command is involved. manage_system { action: "bridge_screenshot" } remains as a compatibility alias.
• 🎥 Video evidence — record_video { action: "start", name: "npc-dialogue" } begins a silent WebM capture of the live game canvas; record_video { action: "stop" } saves it under .mcp-cache/recordings/ and returns its path. Agents can stage repeatable scenes with the allowlisted interact command and fixed-button press_button input—there is still no arbitrary script or eval command.

### 🔒 Security

The plugin returns before anything else runs unless the game is under NW.js *and* was launched with a test argument. A deployed build a player double-clicks never reaches the socket code, or even require('fs').

It checks every argument rather than only argv[0] the way Utils.isOptionValid does, because playtest passes the project path first. So a deployed build *deliberately* launched with a literal test argument would get past the guard — and then find no handshake file, and never connect.

The server binds `