{
"markdown": "\n\n# ๐ฎ RPG Maker MV Ultimate\n\n### An AI copilot that builds, understands and *watches* your RPG Maker MV game\n\n[](https://www.npmjs.com/package/rpgmaker-mv-mcp)\n[](https://www.npmjs.com/package/rpgmaker-mv-mcp)\n[](https://github.com/DiegoLopez0208/RpgMakerMVUltimate-MCP/actions/workflows/ci.yml)\n[](https://registry.modelcontextprotocol.io)\n[](https://nodejs.org)\n[](LICENSE)\n\n**[Quick start](#-quick-start) ยท [What it does](#-what-it-does) ยท [Map generation](#๏ธ-map-generation) ยท [Live bridge](#-the-live-bridge) ยท [Intelligence](#-project-intelligence) ยท [Tools](#-the-13-tools)**\n\n
\n\n---\n\nA [Model Context Protocol](https://modelcontextprotocol.io/) server that lets an AI agent work on a **real RPG Maker MV project on disk** โ database, maps, events, plugins, system โ through **13 consolidated tools** validated against the actual engine, so what comes out is coherent and playable.\n\nIt does three things that are usually missing:\n\n| | |\n|---|---|\n| ๐๏ธ **Builds** | Generates maps that look hand-made, wires events from presets, and edits every database with real IDs instead of invented ones. |\n| ๐ง **Understands** | Reads the whole project and answers *why the door never opens*, *which map nobody can reach*, *which skill breaks the game*. |\n| ๐ **Watches** | Runs the game and reports back: exceptions, player position, screenshots โ and reloads a map you just edited without losing the save. |\n\n
\n\n## โก Quick start\n\n**1 โ Add it to your MCP client.** No clone needed; the package ships an executable.\n\n```json\n{\n \"mcpServers\": {\n \"rpgmaker-mv\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"rpgmaker-mv-mcp\"],\n \"env\": {\n \"RPGMAKER_PROJECT_PATH\": \"C:/path/to/your/RPGMakerMV/project\"\n }\n }\n }\n}\n```\n\n\nClaude Code one-liner, and running from source
\n\n
\n\n```bash\n# Claude Code, user scope\nclaude mcp add rpgmaker --scope user \\\n --env RPGMAKER_PROJECT_PATH=\"C:/path/to/project\" \\\n -- npx -y rpgmaker-mv-mcp\n```\n\n```bash\n# From source\ngit clone https://github.com/DiegoLopez0208/RpgMakerMVUltimate-MCP\ncd RpgMakerMVUltimate-MCP\nnpm install && npm run build\nRPGMAKER_PROJECT_PATH=/path/to/your/project npm start\n```\n\nMCP clients load tool definitions once at startup, so **restart the client** after adding or upgrading the server.\n\n \n\n**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.\n\n**3 โ Let the agent look around first.**\n\n```\nget_project_context { detail: \"full\" } โ what exists, with real IDs\nanalyze_project { view: \"overview\" } โ health, counts, unreachable maps\n```\n\nWorks with Claude Desktop, Claude Code, opencode, and any MCP-compatible client.\n\n
\n\n## ๐งญ What it does\n\n```mermaid\nflowchart LR\n A[\"๐ค Agent\"] -->|\"generate_map ยท manage_map_event\"| B[\"๐ Project on disk\"]\n B -->|\"validate ยท balance ยท metrics\"| A\n B -->|\"playtest\"| C[\"๐ฎ Running game\"]\n C -->|\"exceptions ยท position ยท screenshots\"| A\n A -->|\"reload_map\"| C\n```\n\nThe bottom half of that loop is what the bridge adds. Before it, the agent wrote files and hoped.\n\n
\n\n## ๐บ๏ธ Map generation\n\nTwo paths, both behind `generate_map`. Pick by whether your project uses RTP art.\n\n| | `mode: \"procedural\"` *(default)* | `mode: \"semantic\"` |\n|---|---|---|\n| **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 |\n| **Looks like** | Real multi-tile buildings, walls, furniture | Rooms and corridors shaped by what the space is *for* |\n| **Tilesets** | RTP, or close to it | **Any** โ DLC, itch.io, custom |\n| **Guarantees** | Same `seed` โ same map | Same `seed` โ same map, and the key is always reachable **before** the door it opens |\n\n### The knowledge-driven path\n\n```json\n{ \"mode\": \"procedural\", \"theme\": \"town\", \"name\": \"Riverbend\", \"width\": 40, \"height\": 30 }\n```\n\nThemes 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.\n\n> **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`\n\nOther modes: `blank` (empty canvas), `themed` (simple layout), `template` (one specific bundled map), `batch` (many at once), `duplicate` (copy an existing map).\n\n### The tileset-independent path\n\nThe 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:\n\n```\nmanage_system { action: \"mine_templates\" } # learn from THIS project\ngenerate_map { mode: \"semantic\", tilesetId: 5, rooms: 6, seed: 42 }\n```\n\n- **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/`.\n- **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.\n- The result includes `markers` naming the cell of every mission role, which is where to put events with `manage_map_event`.\n- Pass a mined `templateId` (e.g. `\"mined-3\"`) to re-materialise one of your **own** maps onto a different tileset.\n\n
\n\n## ๐ The live bridge\n\n`playtest` on its own is fire-and-forget: the game opens and nothing comes back. The bridge closes the loop.\n\n```\nmanage_system { action: \"install_bridge_plugin\" } # once per project\nmanage_system { action: \"bridge_start\" } # opens ws://127.0.0.1:32123\nmanage_system { action: \"playtest\" } # the game connects on its own\nmanage_system { action: \"bridge_telemetry\", types: [\"exception\", \"log\"] }\n```\n\n```mermaid\nsequenceDiagram\n participant A as ๐ค Agent\n participant S as ๐ฅ๏ธ MCP server\n participant G as ๐ฎ Game (nwjs)\n A->>S: edit_map\n S->>S: atomic write to Map002.json\n A->>S: bridge_command reload_map\n S->>G: reload_map\n G->>G: reserveTransfer + _needsMapReload\n G-->>S: reload_complete\n A->>S: take_screenshot\n S->>G: capture_screenshot\n G-->>S: PNG in base64\n S-->>A: path for analyze_image\n```\n\n- **๐ก 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`.\n- **โป๏ธ 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.\n- **๐ธ 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.\n\n> ### ๐ Security\n> 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')`.\n>\n> 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.\n>\n> The server binds `127.0.0.1` only, refuses any upgrade carrying a browser `Origin` (cross-site WebSocket hijacking), and requires the session token from `.mcp-bridge.json` โ compared in constant time โ within 5 seconds or the connection is dropped.\n>\n> The command surface is a fixed allowlist with **no `eval` primitive**.\n\n
\n\n## ๐ Project intelligence\n\n`analyze_project` is read-only and fully offline. It models the whole project once, so an agent can reason about a game it did not build.\n\n| View | Answers |\n|---|---|\n| `overview` | **Call this first.** Counts, health summary, maps unreachable from the start |\n| `validate` | Every consistency problem at once โ see below |\n| `explain` | *Why does this never happen?* e.g. \"Switch 12 is gated in 3 places but **never set ON**\" |\n| `usage` | Every event, common event and troop that touches a switch/variable/item, with read-write roles |\n| `graph` | The map transfer network and what is reachable |\n| `ast` | One event's logic as a readable tree |\n| `plugins` | What plugins the project uses, their parameters and commands |\n| `critique` | A designer's **opinion** on one map: dead space, clutter, event spread, monotony |\n| `metrics` | The same map **measured** โ see below |\n| `balance` | Database entries that are out of line with their peers โ see below |\n| `refactor` | Command sequences copy-pasted across events, worth extracting into a Common Event |\n| `search` | Find things by meaning across names, dialogue and descriptions |\n| `index` | The structured digest the other views are built on |\n\n\nvalidate โ the problems the editor never warns about
\n\n
\n\nBroken transfers, missing map files, dangling common-event/item/troop references, duplicate IDs, named-but-unused switches and variables, a bad starting position, unreachable maps โ and actor names written into dialogue as `\\N[id]` that do not resolve.\n\nThat last one is worth its own sentence: the engine resolves `\\N[id]` at draw time, not from any structural parameter, so a bad id passes every other check and the editor shows nothing wrong. The line just renders in-game with a hole where the name should be, and a player finds it before you do.\n\n \n\n\nmetrics โ measured, not judged
\n\n
\n\n- **Reachability** โ flood fill from the *real* entry point. Walkable tiles the player can never get to, and events with no reachable tile beside them, are softlocks rather than style notes.\n- **Dead space** โ the unreachable share of the rectangle, against a band for `expected` (`interior` / `dungeon` / `exterior`).\n- **Shape** โ the walkable area thinned to a one-cell skeleton and read as a graph: endpoints, junctions, cycles, critical path, linearity. Linearity near 1 is a corridor with no choice to make.\n- **Variety** โ Shannon entropy over 5ร5 tile windows: the monotonous-floor problem, measured.\n- **Tension** โ for maps with random encounters, how many steps the player is from a shop, inn or save point.\n\n \n\n\nbalance โ outliers relative to their peers, not to invented thresholds
\n\n
\n\nA skill dealing 400 damage is fine in a game where everything does, and broken in one where nothing else breaks 60. So each entry is scored on a power metric and compared against the *others* in its category: damage per MP for skills, gold per point of ATK+MAT for weapons, gold per DEF+MDF for armors, HP per EXP for enemies.\n\nThe comparison is **leave-one-out** โ an entry is judged against statistics it had no hand in creating. Included in its own numbers, a badly broken entry drags the mean toward itself until it stops looking unusual at all.\n\nDamage formulas are **parsed, never executed** (tokenise โ shunting-yard โ evaluate). One that cannot be read statically is listed under `unreadableFormulas` rather than scored as zero damage, which would pull every average down and hide the very outliers you were looking for.\n\nNarrow with `category`, loosen or tighten with `thresholdSd` (default 2).\n\n \n\n### Offline map inspection\n\n- `query_map { view: \"ascii\", mapId }` โ render a map as a character grid with event markers. The cheapest way to *see* a layout and pick coordinates.\n- `query_map { view: \"validate\", mapId }` โ lint one map for invalid tile IDs, broken transfers and missing event terminators.\n\n
\n\n## ๐งฐ The 14 tools\n\n\nClick to expand the full surface
\n\n
\n\n| Tool | Purpose |\n|---|---|\n| `query_database` | List / get by ID / search any database (actors, classes, skills, items, weapons, armors, enemies, states, troops, tilesets, common events, animations) |\n| `create_database_entry` | Create entries, with presets: `damage_skill`, `healing_skill`, `buff_skill`, `state_skill`, `boss_enemy`, `encounter_troop` |\n| `update_database_entry` | Partial updates (incl. troops & animations); append commands to common events; add enemies to troops |\n| `delete_database_entry` | Delete entries with reference-breakage warnings |\n| `query_map` | Map tree, full map data, events, single event, lint, offline ASCII render |\n| `generate_map` | Knowledge-driven, semantic, procedural, blank, themed, template, batch or duplicate |\n| `edit_map` | Fill tile layers, set display names, organize the map tree, connect two maps, set encounters |\n| `manage_map_event` | Create (presets: npc, chest, teleport, door, shop, inn, boss, puzzle_switch), update, **convert** an NPC into a merchant/inn/sign in place, delete, add commands, bulk-populate |\n| `manage_system` | Title, switch/variable names, starting position, **author a plugin**, **scaffold an editor-openable project**, **playtest**, **open/repair in editor**, **mine templates**, and the **live bridge** |\n| `take_screenshot` | Capture and name a live playtest PNG through the authenticated MCP bridge |\n| `analyze_project` | The read-only intelligence layer above |\n| `get_project_context` | Project digest, asset index, per-tileset tile IDs, bundled-template catalog |\n| `set_project_path` | Switch projects at runtime |\n| `analyze_image` | Optional Vision-AI image analysis, plus offline tileset grid measurement and quadrant colors |\n\nThe 101 fine-grained v4 tool names still work as call aliases. Set `RPGMV_LEGACY_TOOLS=1` to advertise them too.\n\n \n\n
\n\n## ๐ก๏ธ Write safety\n\n- **Atomic.** Every write goes to a temp file and is renamed over the target, so an interrupted call can never leave half-written JSON.\n- **Backed up.** Rotated timestamped copies under `.mcp-backups/` (last N, `RPGMV_BACKUP_KEEP`, default 10).\n- **Previewable.** Pass `dryRun: true` to any mutating tool to see exactly what it would write, without touching disk.\n\n> โ ๏ธ **Close the RPG Maker editor while an agent is working.** The editor holds the project in memory and will overwrite changes when it saves.\n\n
\n\n## โ๏ธ Configuration\n\n| Variable | Required | Description |\n|---|---|---|\n| `RPGMAKER_PROJECT_PATH` | recommended | The project folder (the one with `data/` and `js/`). Optional โ `set_project_path` works at runtime |\n| `RPGMAKER_MV_INSTALL` | for playtest | Engine install root, for `playtest` / `open_editor` / `scaffold_project`. Defaults to the standard Steam path |\n| `RPGMV_BRIDGE_PORT` | optional | Loopback port for the live bridge (default `32123`) |\n| `RPGMV_BACKUP_KEEP` | optional | Backups kept per file (default `10`) |\n| `RPGMV_LEGACY_TOOLS` | optional | `1` also advertises the 101 legacy tool names |\n| `VISION_API_URL` | to enable vision | Base URL of an OpenAI-compatible vision endpoint. **Unset = vision disabled** |\n| `VISION_API_KEY` | optional | Bearer token; only sent when set |\n| `VISION_MODEL` | optional | Model name (default `meta/llama-3.2-90b-vision-instruct`) |\n| `VISION_API_PATH` | optional | Endpoint path (default `/v1/chat/completions`) |\n\n\nVision AI is opt-in
\n\n
\n\n`analyze_image { mode: \"ai\" }` sends a project image (tileset, sprite, screenshot, battler) to any OpenAI-compatible endpoint. Nothing is sent anywhere unless you configure it; the `grid` and `colors` modes and every other tool work fully offline.\n\n```bash\n# OpenAI\nVISION_API_URL=https://api.openai.com VISION_API_KEY=sk-... VISION_MODEL=gpt-4o npm start\n# Ollama (local, no key)\nVISION_API_URL=http://localhost:11434 VISION_MODEL=llava npm start\n```\n\nWorks with OpenAI, Ollama, LocalAI, NVIDIA NIM, vLLM, LiteLLM, or any OpenAI-compatible proxy.\n\n \n\n
\n\n## ๐ Agent Skill\n\nA portable [Agent Skill](https://agentskills.io) teaches any model the crash-free workflow โ build maps with `generate_map`, add content with `manage_map_event` presets, never hand-paint tiles or guess IDs. It lives at [`skill/rpgmaker-mv-mcp/SKILL.md`](skill/rpgmaker-mv-mcp/SKILL.md).\n\n```bash\n# Claude Code / Claude.ai\nnpx degit DiegoLopez0208/RpgMakerMVUltimate-MCP/skill/rpgmaker-mv-mcp ~/.claude/skills/rpgmaker-mv-mcp\n# opencode\nnpx degit DiegoLopez0208/RpgMakerMVUltimate-MCP/skill/rpgmaker-mv-mcp ~/.opencode/skills/rpgmaker-mv-mcp\n```\n\nAlso listed in [awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills).\n\n
\n\n## ๐ Knowledge base\n\n\nStatic reference data extracted from the MV corescript
\n\n
\n\n| File | Content |\n|---|---|\n| `tile-ids.json` | Tile ID ranges, autotile formula, sheet descriptions, layer meanings |\n| `passage-flags.json` | Flag bits, common flags, passage check logic |\n| `event-commands.json` | ~140 event command codes with parameter schemas |\n| `enums.json` | Scope, occasion, hitType, damageType, restriction, and the rest |\n| `trait-effect-codes.json` | Trait codes 11-64, effect codes 11-45 |\n| `database-schemas.json` | Full schemas for every MV data type |\n| `image-paths.json` | `img/` directories, tileset slots, naming conventions |\n| `map-templates.json` | Index of the 106 bundled reference maps |\n| `stamps.json` | Mined multi-tile object stamps (trees, props) per tileset |\n| `maps/` | The 106 RTP reference map JSONs used for template cloning |\n\n \n\n
\n\n## ๐ง Known limitations & roadmap\n\n- Decoration semantics are best-effort in the RTP-template path; rare multi-tile objects may land as single tiles. The mined path keeps multi-tile props whole.\n- Town and dungeon layouts keep improving โ planned: a central plaza or well as a landmark, houses in rows facing roads, fences and yards, richer road networks, more room variety.\n- `mode: \"semantic\"` currently generates dungeon-shaped missions. Town and open-world mission grammars are next, as is using the mined adjacency counts to *decorate* rather than only to describe.\n- `balance` compares like with like inside a category, so a boss will legitimately look like an outlier next to random encounters. Read the flag, not the verdict.\n- The bridge is Windows/nwjs playtest only and needs its plugin installed in the project.\n- Vision AI requires your own endpoint.\n\n
\n\n## ๐ ๏ธ Development\n\n```bash\nnpm install\nnpm run build # tsc compile (+ copies knowledge/ into dist/)\nnpm test # vitest\nnpm run typecheck\nnpm run dev # tsx watch mode\n```\n\n| Where | What |\n|---|---|\n| `src/server.ts` | Tool handlers and MCP transport |\n| `src/toolDefinitions.ts` + `src/router.ts` | The 13-tool surface and its routing |\n| `src/tools/*` | Per-domain CRUD |\n| `src/utils/mapGenerator.ts` | Template cloning and procedural generation |\n| `src/utils/graphGenerator.ts` + `src/utils/materialize.ts` | Mission graphs and the semantic compiler |\n| `src/bridge/*` | The loopback WebSocket and the in-game plugin |\n| `src/intel/*` | The read-only layer behind `analyze_project` |\n| `knowledge/` | Static reference data and bundled maps |\n\n
\n\n## ๐ฌ Feedback\n\nActively developed, and **feedback is very welcome** โ bug reports, weird maps, missing tools, ideas. Open a [GitHub Issue](https://github.com/DiegoLopez0208/RpgMakerMVUltimate-MCP/issues) with what you asked the agent to do and what you got; an exported map JSON or a screenshot helps a lot.\n\n\n
\n\n[](https://glama.ai/mcp/servers/DiegoLopez0208/RpgMakerMVUltimate-MCP)\n\n**MIT** ยท Built for [RPG Maker MV](https://www.rpgmakerweb.com/products/rpg-maker-mv)\n\n
\n",
"bytes": 21454,
"sha": "b8401f6c9e0e51b120dd7881462bee421bd8d37cc07c46adef6bee0ee214c9e1",
"repo_slug": "diegolopez0208/rpgmakermvultimate-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_diegolopez0208_rpgmaker_mv_ult_7fd4300c/readme"
}