RPG Maker MV Ultimate MCP

Analyze images related to the project. mode "ai" sends a project image file (tileset, character sheet, map screenshot, battler) to an external OpenAI-compatible Vision API and returns {analysis, model, tokens_used} — NETWORK SIDE EFFECT: the resized JPEG leaves your machine to the endpoint configured via VISION_API_URL / VISION_API_KEY / VISION_MODEL env vars; fails if the path escapes the project, the file is missing, or the API is unreachable/times out (120 s). mode "grid" measures a base64 PNG tileset offline and returns its 48px grid {cols, rows, totalTiles}. mode "colors" returns the average RGB of a base64 PNG's four quadrants offline (a crude what-is-on-screen check). For precise offline map layout, query_map view "ascii" is usually better than any image analysis.

Read-only project intelligence over an in-memory model of the whole project, cached until data files change. Nothing is written. `view` selects the lens: "overview" (default) title, counts, a health summary with the top issues, and maps unreachable from the start map; "index" maps with event counts, common events, named switches/variables; "validate" every consistency check (transfers to missing maps, missing map files, references to missing common events/items/weapons/armors/troops/animations, duplicate IDs, unused named switches/variables, bad start position, unreachable maps, autotiles the engine cannot draw, image/audio files missing from img/ and audio/) as {issueCount, bySeverity, issues[]}, filter with `severity`; "graph" the map transfer network and reachability; "usage" every event, common event and troop that uses `kind` (switch/variable/common_event/item/weapon/armor/troop/animation/actor/state/map) `id`, with read/write roles; "explain" `target` "switch"/"variable" + `id`: whether it is set, read, gated, a dead write or never set (why a door never opens); `target` "map" + `id`: incoming transfers and what becomes unreachable without it; "ast" one event page (mapId, eventId, page?) or common event (commonEventId) as a logical tree with an outline; "plugins" js/plugins.js merged with each plugin's header (@plugindesc/@param/@command/@help), flagging missing files; "critique" a designer's review of one map (`mapId`) with suggestions and a rough score; "metrics" measurements of one map (`mapId`): reachability from the real entry (unreachable tiles and events are softlocks), dead space against `expected` (interior/dungeon/exterior), walkable skeleton (loops, critical path, linearity), tile entropy, and steps to a shop/inn/save when the map has encounters; "balance" each skill/weapon/armor/enemy against its peers (damage per MP, gold per stat point, HP per EXP), leaving each out of its own statistics; `category`, `thresholdSd` (default 2); formulas are parsed, never executed, and unreadable ones are listed; "refactor" command sequences copy-pasted across events, to extract into a common event; "search" ranks names, dialogue, descriptions and notes against a free-text `query`.

Build a validated RPG Maker MV event-command fragment without writing files or requiring a selected project. Returns {commands, warnings?}; feed commands to insert_event_commands, or nest them in a choice/conditional builder. kind selects the command; only fields belonging to that kind are accepted. Troop-only kinds: enemy_appear, change_enemy_state, abort_battle. Fragments omit the root end marker; complete branches include their required nested end markers. MV Show Text has four parameters (no MZ speakerName); plugin_command emits MV code 356, never MZ 357. IDs accept integers or whole decimal integer strings; constants accept finite numbers. Supported game references are checked when inserting into a project.

Create a new entry in an RPG Maker MV database with the next free ID; the data file is written immediately. Returns the complete created object including its new id. Two forms: with `entity` + `data` it creates a raw entry (omitted fields get engine defaults; data.name is expected); with `preset` it builds a ready-to-use entry from a recipe — damage_skill {name, mpCost, scope, formula, element?, animationId?}, healing_skill {name, mpCost, scope, formula}, buff_skill {name, mpCost, scope, paramId 0-7, turns}, state_skill {name, mpCost, scope, stateId, chance 0-1}, boss_enemy {name, battlerName?, specialSkillId?, params?}, encounter_troop {name, enemyIds[]}. Presets validate their required fields and fail with a validation error when missing. Class entries: data.params accepts 8 stat seeds [HP,MP,ATK,DEF,MAT,MDF,AGI,LUK] expanded to full level 1-99 curves automatically. Not supported for tilesets/animations (author those in the editor). Referenced IDs (classId, stateId, enemyIds...) are NOT validated — confirm them with query_database first.

DESTRUCTIVE: delete a database entry by nulling it out in its data file (written immediately; not undoable — re-create it if needed; IDs are never reused). The delete is refused while anything still references the entry, listing every place: events, common events, troop pages, page conditions, map encounters, the starting party, actor classes and starting equipment, class learnings, enemy actions and drops, troop members, traits, item and skill effects, animations. Fix those first, pass dryRun:true to preview the list, or force:true to delete anyway (the result then lists brokenReferences). References are never cleaned up automatically. NEVER delete skill 1 (Attack), skill 2 (Guard) or state 1 (KO); the engine uses them directly. Supported entities: actors, classes, skills, items, weapons, armors, enemies, states, troops, animations. Returns the deleted object for reference; fails with an error if the ID does not exist.

Modify existing maps; the affected map files / MapInfos.json are written immediately. `action` selects the edit: "fill_layer" overwrites an ENTIRE tile layer with one tile ID (destructive, not undoable; layers: 0-1 ground, 2-3 upper, 4 shadow bits 0-15, 5 region IDs 0-255; tileId 0 clears; find valid IDs with get_project_context detail "tileset"); "set_display_names" sets the player-visible displayName of several maps at once (entries whose map file is missing are reported in `skipped`, not errors); "organize_tree" re-parents maps in the editor tree (purely organizational, gameplay unaffected); "connect" creates a bidirectional pair of transfer events between two maps so the player can walk both ways; "set_encounters" sets the map's random-battle list so enemies appear while walking — `encounters` is [{troopId, weight?, regionSet?}] (weight default 5; regionSet [] = whole map; troopId must exist) plus optional `encounterStep`. WITHOUT encounters set, a map has no random battles. Returns a per-action summary. Fails with an error if a referenced map does not exist (except set_display_names, which skips). "paint" writes one tile into cells or a rect of one layer; an autotile is written as its kind and the painted cells and their neighbours get the shapes the editor would give them, so shorelines and walls join up, while the rest of the map keeps its saved shapes. "repair_autotiles" fixes only autotile cells whose shape the engine cannot draw (analyze_project validate reports them as invalid-autotile). For event-level work use manage_map_event.

Create a new map file (next free map ID, registered in MapInfos.json; both files written immediately). `mode` selects the generator: "blank" makes an empty map you paint later (edit_map fill_layer); "themed" generates a simple tile layout for a theme using the tileset's real tiles; "procedural" is the full generator — for themes with matching RTP reference templates (town, dungeon, interior, castle, world, etc.) it CLONES a hand-authored template from the 106 bundled maps (real 3D buildings, walls, furniture), auto-picking the closest size; for themes without templates (beach, swamp, etc.) it generates procedurally (Perlin terrain, BSP dungeons, cellular caves). Same seed + params = same map. Every mode except blank and duplicate also returns `walkability` per map (walkable tiles, main area, cut-off tiles) and `warnings` when the map is barely walkable or has unreachable pockets. Pass templateId to force a specific template, or useTemplate:false to force procedural. 21 themes incl. snow, volcano, sewer, space_interior; "batch" generates several procedural maps in one call from `batch` specs; "duplicate" copies an existing map (transfer events still point at their ORIGINAL destinations — review them); "template" instantiates one of the 106 bundled reference maps by templateId (list them with get_project_context detail "templates"); "semantic" is the tileset-independent generator — it lays out a MISSION (entrance, key, locked door, treasure, boss, exit, side rooms) as a graph and only then paints it, asking the tileset profile which tile plays each role, so the layout works on ANY tileset including DLC and third-party packs, and the key is always reachable before the door it opens. It returns `markers` naming the cell of every mission role, which is where to place events next. Run manage_system action "mine_templates" first so the profile comes from tiles this project actually uses; pass a mined `templateId` (like "mined-3") to re-materialise one of the project OWN maps onto a different tileset instead of generating a new mission. Returns {mapId, ...} — procedural also returns the seed; batch returns all mapIds keyed for edit_map "connect". Fails with an error on unknown theme/template or unwritable files.

Read-only: pre-digested project knowledge — CALL THIS FIRST in a session. `detail` selects the depth: "full" (default) returns id+name lists for every database, switch/variable names, starting position, and available sprite filenames per img/ folder — everything needed to create content without inventing broken references; "summary" is a cheap health check (entry counts per data file); "assets" scans img/ and Tilesets.json into a complete index (sheet dimensions, autotile kinds, categorized usable tiles, all PNG names); "tileset" returns the categorized usable tile IDs of ONE tileset (ground/water/walls/roof/decoration) for edit_map "fill_layer" — guessing tile IDs produces glitched maps; "templates" lists the 106 bundled reference maps (id, category, theme) usable with generate_map mode "template", optionally filtered by category/theme. Returns one structured object (or array for templates). GOLDEN RULES for good results: (1) build whole maps with generate_map (it stamps real houses/trees and wires encounters) and add content with the manage_map_event presets — do NOT hand-paint tiles or place decorations one tile at a time; (2) never invent tile IDs or sprite/troop/skill IDs — take them from this tool; (3) for enemies to appear, create troops then set encounters (edit_map "set_encounters"), which generate_map does automatically for combat themes.

Insert a complete event-command fragment into a map event page, common event, or troop battle page. Validates the fragment, insertion boundary, resulting list, and supported references before writing. Invalid data refuses the write. Omit position to append before the root end marker; an explicit position must be a safe command boundary (not inside a text continuation or between a block header and its branches). Fragments are rebased to the target indentation. dryRun:true validates and previews without writing or creating backups. Normal writes use the existing atomic backup-protected project writer. Returns target identity, insertion count, the resulting list length and its command codes (listCodes), and warnings; pass verbose:true to also get the full before/after lists. Existing unknown extension commands are advisory; known MZ-only commands are rejected.

Create, change or remove map events; the map file is written immediately. action "create" without `preset` makes a bare event at x/y (empty page unless `pages`; then use add_command or insert_event_commands). With `preset` it builds a ready event: "npc" {name, dialogues[], characterName?, characterIndex?}; "chest" one-time loot {items: [{type item|weapon|armor, id, amount}]}; "teleport" walk-on transfer {destMapId, destX, destY, trigger?}; "door" action-button warp {destMapId, destX, destY, characterName?, characterIndex?, trigger?, lockedSwitchId?, lockedMessage?}, locked until that switch is ON; "shop" {goods: [[type 0 item/1 weapon/2 armor, id, priceType 0 standard/1 custom, price]]}; "inn" {cost?}; "boss" {troopId} one-time battle, game over on loss; "puzzle_switch" {switchX, switchY, doorX, doorY, gameSwitchId, switchName?, doorName?} makes two linked events. A missing destination map, troop, item or switch is refused; an unwalkable or occupied tile is created anyway and listed in `warnings`. "update" overwrites only `fields`. "convert" keeps an event's id, position, name and sprite but replaces its behaviour via `kind`: "merchant" (options.goods, or options.items [{type, id}], options.greeting?), "inn" (options.cost?), "sign" (options.text). "delete" removes it (destructive). "add_command" appends one command before a page's end. "populate" scatters N npc/chest/boss events on random free tiles of the main walkable area of the map (explicit opts.x/opts.y are used as given). Returns the event(s) with ids; fails if the map or event does not exist.

Project-wide settings in data/System.json (writes are immediate), project lifecycle, and the live playtest bridge. action "get" returns `section`: "full" (large), "switches"/"variables" (names by ID; empty means free) or "title". "set_title" sets the game title. "name_switch"/"name_variable" label one by ID (names only). "resize_list" {section, size} sets the highest valid switch/variable id (MV ignores ids past it, silently). "list_backups" {file?} and "restore_backup" {file, backup?} list and restore the copies kept in .mcp-backups before every write; the newest undoes the last write. "set_starting_position" {mapId, x, y} for new games; a tile the player cannot stand on is moved to the nearest walkable one (`relocated`). "create_plugin" writes js/plugins/<name>.js with a proper header (and a pluginCommand hook when `commands` are given) and registers it in js/plugins.js (order is load order); the same `name` replaces it. "scaffold_project" creates a new editor-openable project at `destPath` from NewData (never overwrites; does not switch the active project). "playtest" runs the active project in the bundled nwjs and first closes the game an earlier playtest of it started (`keepRunning` leaves it open); "stop_playtest" closes that game; "open_editor" opens it in RPGMV.exe, repairing a missing Game.rpgproject (Windows; engine from `install`, RPGMAKER_MV_INSTALL or the Steam path). "mine_templates" learns layouts and tile roles from this project for semantic generation. "export_web" builds an HTML5 folder and zip for itch.io (see outDir, zip, prune). Live bridge: "install_bridge_plugin" writes js/plugins/McpBridge.js (active only in playtest); "bridge_start" opens the loopback socket and its handshake; "bridge_status" says whether the game is connected, and why not in lastAuthError; "bridge_telemetry" drains exceptions, logs, scene changes, player position and executing commands (filter `types`, `peek` keeps them); "bridge_command" sends reload_map, reload_database, get_state, teleport_player, interact, press_button or ping; "take_screenshot" captures the live game ("bridge_screenshot" is an alias); "bridge_stop" closes it.

Read-only: query any RPG Maker MV database (data/*.json). Three forms depending on arguments: no id/query lists every non-null entry of the entity; `id` fetches one entry (returns null, not an error, if it does not exist); `query` does a case-insensitive name search (items/weapons/armors/skills also match descriptions). Returns an array (list/search) or a single object/null (id). Use this to discover valid IDs before create/update/delete or before wiring references (class learnings, troop members, chest loot). For maps use query_map; for a digest of everything at once use get_project_context.

Read-only: inspect maps. `view` selects what you get: "infos" lists the map tree from MapInfos.json (ids, names, folder parentIds — no mapId needed); "full" returns one complete MapNNN.json (dimensions, 6-layer tile data, events — can be large); "events" lists a map's events (with `query`, filters by name, case-insensitive); "event" returns one event by eventId (null if absent); "validate" lints a map (invalid tile IDs per layer, missing page terminators, transfers to map 0, Self Switch OFF where ON was likely meant) returning {issueCount, issues[]}; "ascii" renders the map as a character grid with event markers and a legend — the cheapest way to "see" a layout and pick coordinates, entirely offline. Fails with an error if the map file does not exist. For player-visible images use analyze_image instead.

Start or stop recording the live RPG Maker MV playtest canvas through the authenticated MCP bridge. `action:"start"` begins a silent WebM capture inside the game runtime; `action:"stop"` saves it under `.mcp-cache/recordings/` and returns `{path, bytes, mimeType, durationMs, name}`. This captures only the game canvas, not the desktop or credentials. Requires the bridge plugin, a running bridge, and a connected playtest. Optional `name`, `fps` (default 30), and `bitrateKbps` (default 2500) control the artifact.

Play the game headless from a script of steps and report what happened: does the door transfer, does the NPC say the right line, does the choice branch, is a tile blocked. Boots the project in Chromium with the real engine; no editor or running game needed, and project data is never changed (screenshots go to .mcp-cache/renders/). Steps by action: load {mapId,x,y,direction?,party?,level?,gold?,switches?,variables?,selfSwitches?,items?,equip?,encounters?} starts a fresh game there; startEvent {eventId} runs a map event until it shows text or goes idle; advanceText {maxMs?} presses OK until idle, stopping at choices or battle, and returns the lines shown; choose {index}; walk {direction,steps?} reports where the player ended or which tile blocked; press {button,times?}; wait {ms}; autoBattle {troopId?,canEscape?,canLose?,maxMs?} fights on auto until the battle ends; screenshot {name?}; eval {script} returns a JS expression evaluated in the game page. The result lists each step with ok, a finalState and page problems (errors, missing files). Runs can take minutes: send a progressToken to get progress notifications. Needs the optional playwright-core and a cached Chromium (npx playwright install chromium-headless-shell, or RPGMAKER_MCP_CHROMIUM).

Switch this server to a DIFFERENT RPG Maker MV project directory for all subsequent tool calls (session-wide side effect; persists until changed again or the server restarts). Validates that the path contains data/System.json and fails with an error otherwise, leaving the previous project active. Returns the new active path. Without this tool, the RPGMAKER_PROJECT_PATH environment variable set at startup applies.

Capture the current RPG Maker MV playtest frame through the authenticated MCP bridge and save it as a PNG under `.mcp-cache/screenshots/`. Returns `{path, bytes, mimeType, name}` and the PNG itself as an image block (up to 1.5 MB; RPGMV_INLINE_IMAGES=0 turns that off), so you can look at it. Requires `manage_system` actions `install_bridge_plugin`, `bridge_start`, and `playtest` first. Optional `name` becomes a safe filename prefix; each capture keeps a timestamp. `manage_system {action:"bridge_screenshot"}` remains available as a compatibility alias.

Partially update an existing database entry: only the keys in `fields` are overwritten (arrays like traits/learnings/actions are replaced wholesale, not merged); the data file is written immediately and there is no undo, so fetch current values with query_database first if you may revert. Returns the full entry after the update. Fails with an error if the ID does not exist. Special append forms that do not need `fields`: common_events + `appendCommand` inserts one event command before the list terminator; troops + `addEnemyId` adds a member at an auto-computed battle position; troops + `addPage` inserts one battle-event page from a compact trigger. Troops and animations also support plain `fields` updates now (e.g. rename a troop, replace its members/pages, or relabel an animation). Class params in fields accept 8 seeds (expanded to full curves) or 8 arrays of 100 per-level values. Editing tilesets affects every map using them; malformed flags break passability project-wide.