io.github.Redseb/rpgmaker-mz-mcp

Create a complete, placed map-transfer event in one call, using whichever of the two working idioms you pick. `idiom: "action_button"` (default) makes a priority-`same` event the player faces and presses — the right shape for a solid landmark (building, dungeon mouth, door); `idiom: "player_touch"` makes an invisible priority-`below` doormat the player walks onto — for interior exits and map-edge gaps. `direction` is the facing the player lands with, `fade` the screen transition. Throws if the destination map does not exist; warns if the destination tile is outside that map, if the characterName is unknown, or if the event can never fire from where it sits.

Create a new troop (enemy battle group) in data/Troops.json. `name` is required; `members` defaults to empty and `pages` to one blank battle-event page. Every member.enemyId must reference an existing enemy. A structurally invalid battle-event page refuses the write (nothing is saved) — pass force: true to override.

Create a new weapon in data/Weapons.json. Only `name` is required; omitted fields use the editor's new-weapon defaults (Weapon equip slot, no stat bonuses). `params` is a flat 8-length stat bonus [maxHP, maxMP, atk, def, mat, mdf, agi, luk]. Allocates and returns the next unused weapon id.

Delete a map: remove its entry from the map tree (MapInfos.json) and delete its data/MapNNN.json file. The deleted map's direct children are reparented onto its parent (not deleted), so removing one node doesn't wipe a whole sub-tree. Does not touch System.json.

Delete an event from a map by ID

Delete one database record (actor, class, skill, item, weapon, armor, enemy, troop, state, or common_event) by nulling its slot — ids never shift, so nothing else is renumbered. Reports every reference the deletion would leave dangling (an actor's class, a troop member, a Change Items / Shop / Battle Processing command, a skill effect, the starting party, …; found with the same audit validate_references runs, see `coverage` in the response) and REFUSES, writing nothing, when there are any — pass force: true to delete anyway, or dryRun: true to preview the references without throwing. Deleting skill 1 (Attack), skill 2 (Guard) or state 1 (Knockout) is always reported, since the engine hard-codes them. Returns { type, deleted: { id, name }, referenceCount, references[], coverage }.

Decode a raw RPG Maker MZ tile id into its tileset sheet (A1–A5, B–E), and for autotiles its kind + shape slot (0–47) and autotile geometry (floor/wall/waterfall). Read-only inspection helper — raw tile ids are opaque integers, this makes one legible. Returns { tileId, empty, sheet, sheetIndex, autotile, kind?, shape?, autotileType? }. Pass `tilesetId` to also inspect the sheet PNG and report `transparent` (true = the tile is see-through and needs an opaque base tile on a lower layer; painting it on layer 0 alone shows the map void) + `transparentPercent`.

Export a pruned HTML5 web deployment (for itch.io or any static host): copies index.html, js/, css/, fonts/, icon/ and data/*.json, plus only the img/audio/movies files the game references (every string in data/*.json, string literals in the core js and plugins, plugin @default annotations; img/system is always kept) and only the effects/*.efkefc Effekseer effects actually referenced (an animation's effectName, a Plugin Command argument, or a plugin parameter/string — not other data strings) together with the textures/models they list internally. Writes the folder to outDir and, by default, <outDir>.zip with index.html at the archive root. Returns file/byte counts, kept/dropped asset counts (+ dropped paths), the screen size from System.advanced (the itch embed size), and warnings for itch's 1000-file / 200 MB-per-file limits. Writes nothing inside the project; outDir must be outside the project's copied folders, and an existing non-empty outDir is only replaced if it was a previous export_web output. Follow up with a playtest of the exported build.

Fill a rectangular area of a map with one tile id, with automatic autotiling — a filled autotile region borders itself correctly (and re-borders any same-kind tiles it touches). Flat tiles fill uniformly. Defaults to the lower ground layer (0). For region ids, fill layer 5 with the region number as tileId.

Find tiles in a tileset by a case-insensitive SUBSTRING match on their catalog name — a quick bridge from a name fragment like 'grass' or 'forest' to a paintable tile id. This is a literal substring match, NOT synonym/semantic search: 'water' matches 'Endless Waterfall' but not 'Sea' or 'Pond' (their names lack the substring). To browse the actual tile names first, use get_tile_catalog with a `sheet` filter, then search a fragment you see. Set `searchDescriptions: true` to also match the free-text description a project catalog carries (custom sheets named by the tileset-catalog skill — their names are terse, the descriptions say what the tile looks like); built-in RPG Maker entries have no description, so this only widens the search over custom sheets. Returns matching catalog entries (name, sheet, tile id, autotile kind, `source`, `matchedIn` [which fields matched], `transparent` [true = needs an opaque base on a lower layer], plus `description`/`confidence`/`manual` for project catalog drafts). Covers the default RPG Maker tilesets, non-default sheets with a .txt name sidecar in img/tilesets/ (DLC packs ship these; loaded automatically, `source: 'sidecar'`), plus custom sheets cataloged into data/tilecatalog/ (via the tileset-catalog skill). Read-only.

Read a database table in full: actors, classes, items, weapons, armors, skills, enemies, troops, states, or common_events. Returns the raw 1-indexed array (slot 0 is null), or — with `id` — that single record, or null if no such record exists. These are full records: prefer list_names for an id→name index, or search_actors/search_items/search_skills to find records by name, and reach for this only when you need every field. Maps and tilesets are not here: use get_map_infos/get_map and get_tilesets/get_tile_flags. Read-only.

Get the game title

Get map data by ID. The tile `data` array can be huge on a painted map (width*height*6 ints) and blow the MCP token limit, so pass includeData:false to omit it (you get dataTileCount instead) and read tiles with get_map_region when needed. includeData defaults to true for backward compatibility.

Get the width and height (in tiles) of a map

Get a specific event from a map

Get all events from a specific map

Get information about all maps

Read the raw tile ids in a rectangular window of one map layer — a token-cheap alternative to get_map for inspecting part of a painted map. Returns `tiles` as a 2D array (rows top→bottom, each left→right) of raw engine tile ids. The rectangle must lie fully within the map bounds (throws otherwise). layer defaults to 0 (see set_map_tile for the z-layer meanings).

Get the starting party — the actor ids the game begins with. Returns `{ partyMembers }`, rhyming with set_party's input/output shape.

Get the project directory the server is currently operating on: its path, whether it is a valid RPG Maker MZ project, and the game title it holds.

Get the game starting position ({ mapId, x, y })

Get all game switch names

Get system data

Get the game vocabulary/terms: the `basic`, `commands`, `params` string arrays and the `messages` map (menu labels, system messages).

Get the semantic tile catalog for a tileset: the named tiles (e.g. 'Grassland A', 'Forest', 'Sea') in each of its image sheets, each with its representative tile id and a `source` ('builtin' = RPG Maker's own labels; 'sidecar' = authoritative names from an img/tilesets/<Sheet>.txt file shipped next to a non-default sheet, as DLC packs do; 'project' = a data/tilecatalog/ entry — a vision-bootstrap draft, or a human-verified `manual` one, which outranks a sidecar name). Project (custom-sheet) entries also carry the skill's `description`, `confidence` ('high'/'medium'/'low'), and `manual` (true = a human verified it) so you can gauge how trustworthy a draft name is. Autotile entries (A1–A4) return the kind's base tile id — feed it to a paint command, which recomputes the shape from neighbours. Covers the default RPG Maker tilesets, any non-default sheet with a .txt name sidecar in img/tilesets/ (loaded automatically), plus custom sheets cataloged into data/tilecatalog/ (via the tileset-catalog skill); still-uncovered sheets are omitted. **Called WITHOUT `sheet` it returns only a per-sheet index (name + entry count) to stay within the tool-output limit — a full tileset can hold thousands of named tiles. Pass `sheet` (filename 'World_A2' or slot role 'A2') to list one sheet's actual tile entries.** Sheet-filtered entries also carry `transparent` (true = the tile is see-through and needs an opaque base tile on a lower layer — painting it on layer 0 alone shows the map void; e.g. trees/objects/overlays). Read-only.

Decode a tileset's flag word for a single tile id into a legible view: 4-direction passability (down/left/right/up — true = walkable that way), the [*] 'star' overlay bit, ladder/bush/counter/damage-floor flags, and terrain tag (0–7). Read-only inspection of data/Tilesets.json flags[]. Note passability here is for the tile in isolation; a real cell's passability layers its stacked tiles — use check_passability for that. Returns { tilesetId, tileId, tile, flags }.

List every tileset in the project with its id, name, mode (0 world / 1 area), and the image sheets it uses (labelled A1–A4, A5, B–E; empty slots omitted). Use this to discover valid tilesetId values (needed by find_tile, get_tile_catalog, paint_tiles, fill_area, place_object, get_tile_flags, set_tile_flags, check_passability) and to see which sheets each tileset is built from. For a plain id→name list, list_names(type:"tilesets") is even cheaper. Read-only.

Get the title screen settings: title1Name/title2Name (background layers, from list_assets("titles1"/"titles2") — title2Name draws over title1Name), titleBgm (the AudioFile that plays while it is shown), and drawTitle (whether the game title text is drawn over the art).

Get one System.json type-name array — the named lists other data references by index: elements, skillTypes, weaponTypes, armorTypes, or equipTypes.

Get all game variable names

Insert a pre-built sequence of event commands (from the build_* builders) into any of the three command lists an MZ project has — the mutating companion to the read-only builders. Splices before the list’s end marker (or at `position`). target "map_event" (the default) needs mapId + eventId + pageIndex; "common_event" needs commonEventId; "troop_page" needs troopId + pageIndex. The resulting list is validated before writing: a structural problem (wrong parameter count for a command code, a list left unterminated) refuses the write and saves nothing — pass force: true to override. Advisory findings (unrecognized code, over-long text line) are returned as `warnings` and never block. Returns { target, id, listLength, listCodes, warnings? } — the resulting list as its length and its command CODES, which is what you verify a splice against; pass verbose: true for the full list with parameters, or read it back with get_map_event.

Show which switch / variable / common-event IDs are already spoken for, derived from the project's own JSON (never a hand-maintained list, which would drift the moment someone edited in the RPG Maker editor). An id counts as allocated if it is declared (a System.json label, a CommonEvents row) OR referenced anywhere — event page conditions and command lists, common events, troop pages, and Common Event skill/item effects. Use this before reusing an id, and pass `id` to answer "where is switch 23 actually used?" before touching it. Returns { count, highest, gaps, declaredCapacity, allocated[], coverage }. Read-only. To claim a fresh id instead, use next_free_id.

List the available asset filenames (extension stripped) for one asset kind — the exact names RPG Maker's data references (a sprite/face/tileset/audio name). Use it to validate a graphic or audio name before wiring it into an event; a wrong filename fails silently at runtime. Fails soft: an unused asset directory returns an empty list.

Cheap names-only index for a database table. Returns { id, name } entries instead of full records — use it to look up or sanity-check IDs before wiring them into events, without paying the token cost of a full get_*/search_* dump.

List every plugin command create_plugin_command can validate (plugin filename → command key → args): the plugins this project actually ships, scanned from their js/plugins/*.js annotations, merged over a small built-in allowlist. Pass pluginName to narrow to one plugin. Read-only. Use scan_plugins for the richer per-project view (arg types/defaults, enabled state); an unlisted plugin command can still be built, it just isn’t validated.

Reserve the next unallocated switch / variable / common-event ID(s) instead of picking one by hand. Ids are handed out strictly above every id already declared or referenced, so two sessions editing the same project over time cannot silently claim the same switch — a collision that never crashes and only surfaces hours into a playtest as a door that is inexplicably already open. Pass `reuseGaps: true` to fill holes below the highest id first (off by default: a hole is often an id claimed in notes but not yet written). Read-only — it suggests ids, it does not write them; name what you take with set_switch_name / set_variable_name so the next session sees the claim.

Expand a top-left flat tile id + a width×height size into the grid of tile ids that object occupies on the sheet — feed the returned `tiles` straight into place_object. This handles the flat sheets' two-half-column layout, where the tile below id N is NOT N+16 (indices 0–127 are the left half of the sheet, 128–255 the right), which is otherwise painful to compute by hand. Get the top-left id from find_tile/get_tile_catalog. Read-only. Throws if topLeftId isn't a flat id or the rectangle runs off the 16×16 sheet; warns if the tileset lacks that sheet.

Paint a whole map area from an ASCII blueprint in ONE call and one write. `rows` are equal-length strings (one glyph per cell); `legend` maps each glyph to what that cell holds: `[[layer, tile], ...]` pairs (multi-layer cells, e.g. ground on 0 + fence on 1); a bare string = a catalog tile name on layer 0; `{ wall: { top, side?, faceHeight?, layer? }, tiles?: [...] }` = an A4 wall (or A3 roof) — every cell gets the wall-top kind and the bottom `faceHeight` (default 1) cell(s) of each vertical run get the wall-side kind (derived as top + 8 kinds = +384 ids unless `side` is given; a run continuing off the map's bottom edge gets no face); or `null` = leave the cell untouched. Tiles may be ids or catalog names (exact name, else a unique substring — unknown/ambiguous names are an error). Row lengths, unknown glyphs, names and fit are all validated before anything is written. With `clearUpperLayers` (default true) each painted cell zeroes the tile layers (0-3) above its lowest specified layer that it does not specify, so stale objects vanish (`[]` erases the cell). Autotiling is recomputed once per layer, as in paint_tiles. Returns cells painted per layer, cleared count, wall faces made, and a passability overview of the rectangle, judged like the engine's canPass (a step needs the source to allow leaving and the target to allow entry): `rows` with `#` = impassable — a cell with no walkable direction (face, water, solid object) or part of a region whose own edge flags refuse entry from the walkable cells around it (an A4 wall-top mass, a stair-less plateau) — and `.` = walkable ground, plus the impassable [x, y] cells. Stamp multi-tile B/C objects afterwards with place_object.

Paint specific tiles onto a map, with automatic autotiling. Each cell is set to its tile id; if that id is an autotile (A1-A4, e.g. a catalog 'kind' base from find_tile), its shape and its neighbours' shapes are recomputed from same-kind adjacency so borders/corners line up. Flat tiles are painted as-is. Defaults to the lower ground layer (0). Higher-level than set_map_tile, which is a single raw tile with no autotiling.

Place a multi-tile B/C object (a house, tree, fountain, …) on a map and report its passability. `tiles` is the object's block of flat tile ids as rows (top to bottom), each row left to right; a 0 leaves that cell untouched so L-shaped/irregular objects work. Stamped onto the upper tile layer (2) by default so it draws over the ground. Unlike paint_tiles this does NOT autotile (objects are flat sheet tiles) — instead it uses the tileset flags to warn when a footprint cell sits on impassable terrain or overwrites an existing tile, and returns the resulting per-cell passability plus the `collision` cells the object turns into a solid obstacle. Warn-by-default: never refuses a placement. Get tile ids from find_tile/get_tile_catalog.

Screenshot a map as the game actually draws it: boots the project headless, starts a new game on the map, and saves a PNG. Validators prove structure, not looks — use this to catch wrong wall/autotile kinds, void (unbased transparent tiles), odd sprites or missing images. Default renders the WHOLE map (canvas resized to width×height×48px, player hidden, autorun/parallel events frozen, map-name banner off); pass x+y for a normal 816×624 game-screen view centred on that tile. Returns the PNG path plus `problems` — console errors, page errors and HTTP 404s (missing assets — a missing image is drawn blank instead of stopping the engine on its load-error retry screen). Read-only. Needs the optional dependency playwright-core and a Chromium from the Playwright cache (`npx playwright install chromium-headless-shell`) or the RPGMAKER_MCP_CHROMIUM env var.

Clear a whole database table (actor, class, skill, item, weapon, armor, enemy, troop, state, or common_event) except the ids in `keep` — e.g. reset_table('skill', { keep: [1, 2] }) wipes the RTP skills but keeps Attack/Guard, the usual first step before authoring your own database with batch_create. Kept records stay at their own id; the rest become null and trailing empty slots are trimmed (the table is [null] when nothing is kept). Like delete_record it REFUSES, writing nothing, when the removal would leave references dangling (map events giving removed items, troops of removed enemies, …) unless force: true; use dryRun: true first to see what disappears and what would break. Returns { type, kept[], removedCount, removed[], referenceCount, references[], coverage } (lists are capped at 100).

Resize a map to new width/height, safely repadding every z-layer of its tile data (existing tiles kept where the old and new grids overlap; new cells blank; shrinking crops). This is the ONLY safe way to change a map's dimensions — update_map refuses a width/height change because it would not resize the tile array. Warns about any event left outside the new bounds.

Play the game headless from a script of steps and report what happened — the runtime check validators cannot do (does the door transfer, does the NPC say the right thing, does the choice branch, is there an invisible wall). One browser session runs the whole script; each step reports its outcome and the run stops at the first failing step. Steps: `load` {mapId,x,y,direction?,party?,level?,gold?,switches?,variables?,selfSwitches?,items?,equip?,encounters?} starts a fresh game there (random encounters off unless encounters:true); `startEvent` {eventId} starts a map event as if triggered and lets it run until it shows text or goes idle (waiting out any transfer — reported as `transferredTo`); `advanceText` {maxMs?} presses OK until the event is idle, STOPPING at an open choice list/battle — returns the map message `lines` shown and any open choices (text shown during a battle comes back separately as `battleLines`); `choose` {index} picks a 0-based choice; `walk` {direction, steps?} walks tile by tile, reporting where it ended (`to`); if a tile refused entry, `stoppedAt` (the player's tile) and `blockedTile` (the refused one); when a step fires a touch event (a door) it stops, waits out the transfer and reports `transferredTo` {mapId,x,y}, plus `eventRunning`/`messageOpen` if the event is still going; `press` {button, times?}; `wait` {ms}; `autoBattle` {troopId?, canEscape?, canLose?, maxMs? (default 60000)} fights (a started or new battle) on auto AI until it ends, returning the battle's message `lines` (troop events, victory text). Battles are fast-forwarded (20 engine frames per drawn frame: same logic, same odds, a 10-turn boss fight in seconds) unless the run sets realtime: true; `screenshot` {name?} saves a PNG; `eval` {script} evaluates a JS expression in the game page and returns its value (e.g. "$gameSwitches.value(3)"). Reported text reads as the message window shows it: \V[n]/\N[n]/\P[n]/\G expanded, control codes (\C[n], \I[n], \., \| …) removed. Every ste…

Discover the plugin commands this project actually has, by parsing the @command/@arg annotations in js/plugins/*.js and the enabled/disabled state in js/plugins.js. Use it to find out what create_plugin_command can call and with which args — it reports every command's key, label, description and args (name/type/default), plus whether the plugin is enabled in the editor's Plugin Manager (a disabled plugin's commands never run). create_plugin_command validates against this scan automatically, so you don't need to call this first; it's for discovery. Pass pluginName to narrow to one plugin, or enabledOnly:true to skip plugins that are installed but switched off. Read-only. NOTE: MZ has no 'required argument' annotation, so scanned args are checked for unknown names only, never for missing ones.

Search actors by name or nickname

Search enemies by name (case-insensitive)

Search items by name or description

Search events on a map by name

Search skills by name or description