Skip to main content
Glama

๐ŸŽฎ RPG Maker MV Copilot MCP

Find why an MV event never fires โ€” then verify the fix in the real engine

npm downloads CI MCP Registry node license

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):

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, 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.

Related MCP server: RPG Maker MZ MCP Server

๐Ÿงญ 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.

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

{ "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 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.

The command surface is a fixed allowlist with no eval primitive.

๐Ÿ” Project intelligence

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.

View

Answers

overview

Call this first. Counts, health summary, maps unreachable from the start

validate

Every consistency problem at once โ€” see below

explain

Why does this never happen? e.g. "Switch 12 is gated in 3 places but never set ON"

usage

Every event, common event and troop that touches a switch/variable/item, with read-write roles

graph

The map transfer network and what is reachable

ast

One event's logic as a readable tree

plugins

What plugins the project uses, their parameters and commands

critique

A designer's opinion on one map: dead space, clutter, event spread, monotony

metrics

The same map measured โ€” see below

balance

Database entries that are out of line with their peers โ€” see below

refactor

Command sequences copy-pasted across events, worth extracting into a Common Event

search

Offline Unicode text matching across names, dialogue, descriptions and notes; no synonym or translation expansion

index

The structured digest the other views are built on

Broken 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.

That 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.

  • 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.

  • Dead space โ€” the unreachable share of the rectangle, against a band for expected (interior / dungeon / exterior).

  • 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.

  • Variety โ€” Shannon entropy over 5ร—5 tile windows: the monotonous-floor problem, measured.

  • Tension โ€” for maps with random encounters, how many steps the player is from a shop, inn or save point.

A 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.

The 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.

Damage 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.

Narrow with category, loosen or tighten with thresholdSd (default 2).

When a search returns nothing

Search returns searchMode: "lexical", complete, indexedFiles, skippedFiles and warnings. complete: false means some data could not be read; it does not mean the game contains no matching content. An empty result includes noResultsReason. Use a name or phrase actually present in the project: herrero does not translate into Blacksmith. Unicode names, including Japanese, are supported. A database query for an absent ID can return null; inspect it before using that ID.

Index, overview, validation, graph, usage, explain and refactor also report incomplete input. Unreadable files appear as validation errors.

Offline map inspection

  • 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.

  • query_map { view: "validate", mapId } โ€” lint one map for invalid tile IDs, broken transfers and missing event terminators.

Tools

The server exposes 18 consolidated tools. The legacy aliases are optional.

Tool

Purpose

build_event_commands

Read-only MV dialogue, choices, conditions, switches, variables, transfers, common-event, flow, and plugin-command builders

insert_event_commands

Validated insertion into map/common/troop event lists, with before/after previews and safe nested boundaries

query_database

List / get by ID / search any database (actors, classes, skills, items, weapons, armors, enemies, states, troops, tilesets, common events, animations)

create_database_entry

Create entries, with presets: damage_skill, healing_skill, buff_skill, state_skill, boss_enemy, encounter_troop

update_database_entry

Partial updates (incl. troops & animations); append commands to common events; add enemies to troops

delete_database_entry

Delete entries with reference-breakage warnings

query_map

Map tree, full map data, events, single event, lint, offline ASCII render

generate_map

Knowledge-driven, semantic, procedural, blank, themed, template, batch or duplicate

edit_map

Fill tile layers, set display names, organize the map tree, connect two maps, set encounters

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

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

take_screenshot

Capture and name a live playtest PNG through the authenticated MCP bridge, or with mapId render a map headless as the engine draws it, no game running

run_playtest

Play a script of steps headless (load, start an event, read its text, choose, walk, battle, screenshot) and report what happened

record_video

Start or stop a named live playtest WebM recording through the authenticated MCP bridge

analyze_project

The read-only intelligence layer above

get_project_context

Project digest, asset index, per-tileset tile IDs, bundled-template catalog

set_project_path

Switch projects at runtime

analyze_image

Optional Vision-AI image analysis, plus offline tileset grid measurement and quadrant colors

The 101 fine-grained v4 tool names still work as call aliases. Set RPGMV_LEGACY_TOOLS=1 to advertise them too.

๐Ÿ›ก๏ธ Write safety

For composed event logic, use build_event_commands followed by insert_event_commands with dryRun:true. The preview includes the exact old and proposed command lists. See Event command authoring for the supported kinds, nesting rules, MV-specific differences, and verification.

  • Atomic. Every write goes to a temp file and is renamed over the target, so an interrupted call can never leave half-written JSON.

  • Backed up. Rotated timestamped copies under .mcp-backups/ (last N, RPGMV_BACKUP_KEEP, default 10). A backup failure aborts replacement. Writes use unique temporary files and exclusive per-file locks; changes detected since a data read are refused. Close the editor: it does not honor MCP locks, and multi-file operations are not transactions.

  • Previewable. Pass dryRun: true to any mutating tool to see exactly what it would write, without touching disk.

โš ๏ธ Close the RPG Maker editor while an agent is working. The editor holds the project in memory and will overwrite changes when it saves.

โš™๏ธ Configuration

Variable

Required

Description

RPGMAKER_PROJECT_PATH

recommended

The project folder (the one with data/ and js/). Optional โ€” set_project_path works at runtime

RPGMAKER_MV_INSTALL

for playtest

Engine install root, for playtest / open_editor / scaffold_project. Defaults to the standard Steam path

RPGMV_BRIDGE_PORT

optional

Loopback port for the live bridge (default 32123)

RPGMV_BACKUP_KEEP

optional

Backups kept per file (default 10)

RPGMV_LEGACY_TOOLS

optional

1 also advertises the 101 legacy tool names

RPGMAKER_MCP_CHROMIUM

optional

Chromium executable for headless renders and run_playtest. Without it the newest browser in the Playwright cache is used (npx playwright install chromium-headless-shell). Headless tools also need the optional playwright-core dependency.

RPGMV_TOOLSET

optional

Advertise only some tool groups, e.g. events,media. core (project, database, maps, events, system, analysis) is always on; the others are events (build/insert event commands), mapgen (generate_map) and media (screenshot, video, image analysis, headless playtest). Unset or all lists everything. core alone is about 11k tokens instead of 18k.

VISION_API_URL

to enable vision

Base URL of an OpenAI-compatible vision endpoint. Unset = vision disabled

VISION_API_KEY

optional

Bearer token; only sent when set

VISION_MODEL

optional

Model name (default meta/llama-3.2-90b-vision-instruct)

VISION_API_PATH

optional

Endpoint path (default /v1/chat/completions)

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.

# 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

Works with OpenAI, Ollama, LocalAI, NVIDIA NIM, vLLM, LiteLLM, or any OpenAI-compatible proxy.

๐ŸŽ“ Agent Skill

A portable Agent Skill 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.

# 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

Also listed in awesome-claude-skills.

๐Ÿ“š Knowledge base

File

Content

tile-ids.json

Tile ID ranges, autotile formula, sheet descriptions, layer meanings

passage-flags.json

Flag bits, common flags, passage check logic

event-commands.json

~140 event command codes with parameter schemas

enums.json

Scope, occasion, hitType, damageType, restriction, and the rest

trait-effect-codes.json

Trait codes 11-64, effect codes 11-45

database-schemas.json

Full schemas for every MV data type

image-paths.json

img/ directories, tileset slots, naming conventions

map-templates.json

Index of the 106 bundled reference maps

stamps.json

Mined multi-tile object stamps (trees, props) per tileset

maps/

The 106 RTP reference map JSONs used for template cloning

๐Ÿšง Known limitations & roadmap

  • 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.

  • 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.

  • 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.

  • 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.

  • The bridge is Windows/nwjs playtest only and needs its plugin installed in the project.

  • Vision AI requires your own endpoint.

๐Ÿ› ๏ธ Development

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

Where

What

src/server.ts

Tool handlers and MCP transport

src/toolDefinitions.ts + src/router.ts

The 13-tool surface and its routing

src/tools/*

Per-domain CRUD

src/utils/mapGenerator.ts

Template cloning and procedural generation

src/utils/graphGenerator.ts + src/utils/materialize.ts

Mission graphs and the semantic compiler

src/bridge/*

The loopback WebSocket and the in-game plugin

src/intel/*

The read-only layer behind analyze_project

knowledge/

Static reference data and bundled maps

๐Ÿ’ฌ Feedback

Actively developed, and feedback is very welcome โ€” bug reports, weird maps, missing tools, ideas. Open a GitHub Issue with what you asked the agent to do and what you got; an exported map JSON or a screenshot helps a lot.

DiegoLopez0208/RpgMakerMVUltimate-MCP MCP server

MIT ยท Built for RPG Maker MV

Available Tools

18 tools
analyze_imageA
Read-onlyIdempotent

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.

Inputs: mode, prompt, base64PNG, imagePath, +1 more.

analyze_projectA
Read-onlyIdempotent

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.

Inputs: id, kind, page, view, +11 more.

build_event_commandsA
Read-onlyIdempotent

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.

Inputs: kind (required), x, y, pan, +79 more.

create_database_entryA

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.

Inputs: data, entity, preset, entries.

delete_database_entryA
DestructiveIdempotent

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.

Inputs: id (required), entity (required), force.

edit_mapA
DestructiveIdempotent

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.

Inputs: action (required), posA, posB, rect, +10 more.

generate_mapA

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.

Inputs: loop, mode, name, note, +20 more.

get_project_contextA
Read-onlyIdempotent

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.

Inputs: theme, detail, category, tilesetId.

insert_event_commandsA

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.

Inputs: commands (required), mapId, dryRun, target, +6 more.

manage_map_eventA
Destructive

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.

Inputs: mapId (required), action (required), x, y, +32 more.

manage_systemB
Idempotent

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/.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.

Inputs: action (required), x, y, id, +36 more.

query_databaseA
Read-onlyIdempotent

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.

Inputs: entity (required), id, query.

query_mapA
Read-onlyIdempotent

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.

Inputs: view (required), layer, mapId, query, +3 more.

record_videoA

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.

Inputs: action (required), fps, name, timeoutMs, +1 more.

run_playtestA

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).

Inputs: steps (required), realtime.

set_project_pathA
Idempotent

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.

Inputs: path (required).

take_screenshotA

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.

Inputs: x, y, name, mapId, +5 more.

update_database_entryA
DestructiveIdempotent

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.

Inputs: id (required), entity (required), fields, addPage, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A3.9/5.0

    Scored across 18 tools

    Disambiguation3/5

    Most tools are distinguishable by name, but there is real overlap among the read-only intelligence tools: analyze_project, get_project_context, query_map, and query_database all expose project/asset inspection, and validation/search appears in both analyze_project and query_map. Transfer-event creation also exists in both edit_map ('connect') and manage_map_event ('teleport'/'door'), and take_screenshot duplicates manage_system's bridge_screenshot alias. Descriptions disambiguate somewhat, but an agent can plausibly misselect.

    Naming Consistency5/5

    Every tool follows a clean snake_case verb_noun pattern (query_database, create_database_entry, edit_map, manage_map_event, take_screenshot, set_project_path). Verbs are used consistently and predictably (query/get/analyze for reads, create/update/delete for writes, manage/edit for mutation). No mixed conventions.

    Tool Count4/5

    18 tools is reasonable for a full RPG Maker MV authoring suite spanning analysis, database CRUD, map generation/editing, events, system settings, playtest, and media capture. The count is slightly inflated in practice because several tools (analyze_project, manage_system, edit_map, manage_map_event, generate_map) bundle many internal actions/views, but the top-level surface stays well-scoped.

    Completeness4/5

    Coverage is broad: full database CRUD, map generate/edit/query, event presets and command building/insertion, system settings, playtest, screenshots, video, and image analysis โ€” a genuinely complete authoring lifecycle with backups. Minor gaps remain, notably no delete/rename-map operation (only create/edit/query) and no direct tile/plugin removal, though these are largely workable via other tools.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers