DiegoLopez0208/RpgMakerMVUltimate-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 · First useful result · Map generation · Live bridge · Intelligence · 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:
| | |
|---|---|
| 🏗️ **Builds** | Generates maps that look hand-made, wires events from presets, and edits every database with real IDs instead of invented ones. |
| 🧠 **Understands** | Reads the whole project and answers *why the door never opens*, *which map nobody can reach*, *which skill breaks the game*. |
| 👀 **Watches** | Runs the game and reports back: exceptions, player position, screenshots — and reloads a map you just edited without losing the save. |
⚡ 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):
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
Claude Code one-liner, and running from source
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.**
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
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.
| | mode: "procedural" *(default)* | mode: "semantic" |
|---|---|---|
| **How** | Clones a hand-authored map from the **106 bundled RTP templates**, closest size first | Lays out a **mission graph**, then paints it through a tileset profile |
| **Looks like** | Real multi-tile buildings, walls, furniture | Rooms and corridors shaped by what the space is *for* |
| **Tilesets** | RTP, or close to it | **Any** — DLC, itch.io, custom |
| **Guarantees** | Same seed → same map | Same seed → same map, and the key is always reachable **before** the door it opens |
The knowledge-driven path
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).