redseb/rpgmaker-mz-mcp

Quick start

Claude Code (recommended) — installs the server and the authoring skills as one plugin:

claude plugin marketplace add Redseb/rpgmaker-mz-mcp
claude plugin install rpgmaker-mz@rpgmaker-mz-mcp

You’ll be prompted for your RPG Maker MZ project directory (optional — you can also just ask Claude to set_project later).

Any other MCP client — the server is on npm; no clone or build needed:

{
  "mcpServers": {
    "rpgmaker-mz": {
      "command": "npx",
      "args": ["-y", "rpgmaker-mz-mcp@latest"],
      "env": { "RPGMAKER_PROJECT_PATH": "/path/to/your/rpgmaker/project" }
    }
  }
}

Claude Desktop — either the JSON config above, or download the one-click rpgmaker-mz-mcp.mcpb bundle from Releases and open it with Claude Desktop.

New here? Read SETUP.md for the full walkthrough and EXAMPLES.md for end-to-end recipes.

Contents

• Quick start
• Capabilities
• How it fits together
• Installation
• Configuration
• Usage
• Available tools
• Input validation
• Event validation (throw-by-default)
• Reference linting
• Dry-run preview
• Custom-tileset catalog skill
• Example prompts
• Development
• Project structure
• Safety and best practices
• Limitations

Capabilities

• Database CRUD — actors, classes (with learnings & param curves), skills (full-control + simplified damage/heal/buff/state helpers), items, weapons, armors, states, enemies, and troops. Only a name is required to create; everything else falls back to the editor’s true “New X” template.
• Maps & the map tree — create/delete maps, batch-reparent/reorder/rename with a cycle guard, and edit map properties. New maps register in MapInfos.json exactly as the editor expects.
• Tile painting (with automatic autotiling) — paint_tiles/fill_area set tiles on any of the six map layers and recompute autotile shapes (and their neighbours’) from same-kind adjacency, so a filled region borders itself correctly. paint_blueprint paints a whole area from ASCII rows + a legend in one call (multi-layer cells, catalog names, A4 wall faces derived automatically) and returns a passability overview. place_object stamps multi-tile B/C objects (houses, trees) and reports their passability footprint.
• Semantic tile catalog — find_tile "grass" → a paintable tile id. Built-in catalogs for every default tileset (Overworld, Outside, Inside, Dungeon, SF), sourced from RPG Maker’s own English name sidecars. A bundled vision-bootstrap skill catalogs custom tilesets.
• Passability & terrain — read a tile’s flags or a map cell’s layered passability (get_tile_flags/check_passability), and edit passability/terrain-tag/behaviour flags (set_tile_flags).
• Event-command builders — high-level, read-only builders that emit the exact EventCommand sequences the editor writes (including tricky recursive branch blocks and continuation rows), landed on a page via insert_event_commands. Covers dialogue & flow, game-state changes, presentation/transitions, and scene processing.
• Event & NPC ergonomics — create_npc places a complete talking NPC in one call; set_event_page merges a page’s graphic + behavior in place.
• Asset awareness — list_assets enumerates valid character/face/tileset/audio names so events never reference a missing file.
• See and play the build — render_map screenshots a map exactly as the engine draws it (whole map or a game-screen view) and run_playtest drives a scripted headless session (load a state, trigger events, read dialogue, pick choices, walk, auto-battle, screenshot), both reporting console errors and missing assets. Validators prove structure; these show what the player sees.
• Correctness layer — Zod-validated inputs, throw-by-default event validation (a structurally invalid write is refused, not saved-and-warned-about), a cross-file reference linter (validate_references), and a dry-run/diff preview on every write.

How it fits together

Installation

Pick one:

• Claude Code plugin (recommended) — claude plugin marketplace add Redseb/rpgmaker-mz-mcp, then claude plugin install rpgmaker-mz@rpgmaker-mz-mcp. This bundles the MCP server (run via npx from the npm package) together with the two authoring skills (rpgmaker-authoring, tileset-catalog) — the skills carry the judgment the tools don’t enforce, so this is the full experience.
• npm package — configure your MCP client to run npx -y rpgmaker-mz-mcp@latest (see Quick start). Tools only, no skills.
• MCPB bundle (Claude Desktop) — download rpgmaker-mz-mcp.mcpb from Releases, open it with Claude Desktop, and pick your project folder in the install dialog.
• From source (development):

npm install
npm run build

Configuration

Set the RPG Maker MZ project path as an environment variable:

# macOS/Linux
export RPGMAKER_PROJECT_PATH=/path/to/your/rpgmaker/project

# Windows
set RPGMAKER_PROJECT_PATH=C:\path\to\your\rpgmaker\project

The path must point to a directory containing game.rmmzproject and a data/ directory with System.json.

The environment variable is only the startup default: the set_project tool can retarget a running server at a different project (and get_project reports the current one), so switching games doesn’t require editing config or restarting.

Usage

Running the server

npm start          # or: node dist/index.js

Configuring in Claude Desktop

The easiest path is the .mcpb bundle from Releases — open it with Claude Desktop and pick your project folder. To configure by hand instead, add to your Claude Desktop configuration file (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "rpgmaker-mz": {
      "command": "npx",
      "args": ["-y", "rpgmaker-mz-mcp@latest"],
      "env": {
        "RPGMAKER_PROJECT_PATH": "/path/to/your/rpgmaker/project"
      }
    }
  }
}

(For a from-source checkout, use "command": "node" with "args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"] instead.)

Available tools

All 128 tools, grouped by area. Tools that write to the project accept an optional dryRun argument (see Dry-run preview); those that can refuse a structurally invalid write also accept force (see Event validation).

Input validation

Every tool declares its arguments as a Zod schema. The server (built on the MCP SDK’s high-level McpServer) validates incoming arguments against that schema before a handler runs, so malformed calls are rejected with a clear Input validation error naming the offending field instead of writing garbage to disk.

Event validation (throw-by-default)

Event command lists are checked against a table of known RPG Maker MZ command codes (101 Show Text, 201 Transfer Player, 122 Control Variables, …), and against the block structure those commands form. Findings come in two tiers, and the tier decides what happens to the write:

• Structural — a wrong parameter count for a known command (including the counts that depend on a Conditional Branch’s condition type or a Control Variables operand type), a list not terminated by the code-0 end marker, a non-array parameters, a broken block (a Show Choices/Conditional Branch/Loop that is never closed, a branch or closer row orphaned or written at the wrong indent, a choice with no When branch), or an action-button event stranded on an impassable tile. These are almost always bugs, so the event-writing tools validate the would-be result before committing and refuse the write: the tool errors and nothing reaches disk. Pass force: true to write anyway (the argument is advertised on exactly the tools that can refuse).
• Advisory — an unrecognized command code (which may simply be a plugin command), an over-long text line, an unknown asset filename, a choice block whose Cancel routing and When Cancel branch disagree (dead code, not corruption). These are legitimately possible, so they never block; they ride along as warnings on the normal response.

Because the check runs before the commit, a dryRun of a write that would be refused fails too, rather than previewing a write that could never happen.

validate_event / validate_project remain read-only audits: they report both tiers (each finding carries a severity) without changing anything.

Text width: teaching it your font

The over-long-text-line warning is measured in characters by default — 55 per line, 38 when a face graphic is shown — which suits the stock RTP font and needs no setup. If your project ships a different font, that estimate goes wrong in one of two directions: a narrower font makes it warn on lines that fit comfortably, and a wider or larger one makes it stay quiet on lines that really are cut off (38 characters of a 24px glyph is 912px in a 616px window). No single character limit fixes both, because glyph widths in a proportional font span a wide range — a full stop can be a third the width of a capital.

Drop a .rpgmaker-mcp.json in the project root to replace the estimate with a real measurement:

{
  "text": {
    "lineBudget": { "noFace": 784, "withFace": 616 },
    "nameBudgetChars": 8,
    "charWidths": { "_default": 13, "a": 11.38, ".": 4.88, " ": 8.12 }
  }
}

• lineBudget — the message window’s usable width, without and with a face graphic. In pixels if you give charWidths, otherwise in characters (a bare lineBudget is just a character-limit override).
• charWidths — per-character advance; _default covers anything unlisted. Get these from the engine itself: Window_Base.textWidth(c.repeat(40)) / 40 in a running game is exact.
• nameBudgetChars — how wide to assume \N[3] / \P[1] renders. A name is typed by the player at runtime, so budget the Name Input maxLength (usually 8) rather than the default name, or a long name overflows a line that fitted while you were testing. Defaults to 0, which ignores name escapes as before.

Everything fails soft: no file, bad JSON, or a malformed text section leaves the built-in estimate in place, so a broken config is never worse than no config. The file is re-read when its mtime changes, and warnings then report real widths (Show Text line is 650px but the message window fits 616px with a face shown).

Auto-wrap. Rather than fixing overflowing lines by hand, pass wrap: true to build_show_text or create_npc and write whole paragraphs: the text is word-wrapped to exactly the width the warning checks (the default estimate or your .rpgmaker-mcp.json metrics; escape codes like \C[n] never count or get split) and split into as many 4-line message boxes as needed, each with the same face/speaker. wrap: true (or "soft") reflows every entry as one paragraph; "hard" keeps each entry and \n as a forced line break and only wraps lines that are too long.

Reference linting

validate_references performs a cross-file id-integrity audit — orthogonal to the command-shape check above. It walks the whole database and flags references that point at something that doesn’t exist: a starting party member with no matching actor, a Transfer Player targeting a missing map, a skill effect that adds a non-existent state, an enemy dropping an unknown item, a cyclic map-tree parent, and more. Every check is warn-by-default and guarded against false positives on partially-loaded projects.

Deleting records and resetting tables

A new MZ project ships RTP-flavoured database rows whose icons, animations and battlers point at RTP art. When you replace the art wholesale, the natural workflow is “clear the database, then author my own” — reset_table is that first step, and delete_record removes a single row.

Database arrays are index = id, so both tools null the slot rather than splice: nothing is renumbered, and no surviving reference silently starts pointing at a different record. reset_table keeps each keep id at its own index and trims trailing empty slots (a table with nothing kept becomes [null]); new records from create_* / batch_create then allocate from the highest live id.

Before writing, both tools work out which references the removal would leave dangling, by running the validate_references audit with and without the removed rows and keeping only the findings the removal introduces (references that were already broken aren’t blamed on it). Removing skill 1 (Attack), skill 2 (Guard) or state 1 (Knockout) is always reported too, since the engine hard-codes those ids. If anything would dangle, the write is refused and nothing reaches disk — pass force: true to go ahead anyway, or dryRun: true to preview what disappears and what would break (a dry-run reports requiresForce instead of throwing). The scan covers what validate_references covers and says so in a coverage field: traits, actor starting equipment, event page conditions, Conditional Branch operands, and Script/plugin commands are not scanned.

reset_table({ type: 'skill', keep: [1, 2], dryRun: true })   // what goes, what breaks
reset_table({ type: 'skill', keep: [1, 2], force: true })    // do it
batch_create({ type: 'skill', records: [...] })              // author the replacements

ID allocation

Switches, variables and common-event IDs are one global namespace, and nothing in RPG Maker stops a later edit from claiming an ID an earlier one already used. The failure is silent — no crash, no validator hit, just a door that is inexplicably already open hours into a playtest.

list_allocated_ids answers “what’s taken?” from the project files themselves — 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. Both halves matter — a named-but-unused switch is a claim someone staked, and a used-but-unnamed one is a claim nobody wrote down. Pass id to ask the narrower question: where is switch 23 actually used, before I touch it?

next_free_id hands back the next unallocated ID(s), strictly above everything already taken. Holes below the highest ID are left alone by default (a hole is often an ID claimed in notes but not yet written); reuseGaps: true fills them when you’re compacting deliberately. It’s read-only — it suggests IDs, it doesn’t write them, so name what you take with set_switch_name / set_variable_name to make the claim visible to whoever edits next. Those two grow the System.json name list when the ID is past the end, so an ID from next_free_id can always be labelled without opening the editor.

Like the command validator, the usage scan is curated, not exhaustive: it covers the commands that carry switch/variable IDs (Control Switches/Variables, Conditional Branch, the “designation by variable” forms of Transfer Player, Change Gold/Items, Change HP/MP/EXP/Level, …), and every report states the command codes it scanned. An ID used only from a Script (355) or a plugin command (357) will read as free.

Dry-run preview

Every tool that writes to the project accepts an optional dryRun argument. When dryRun: true, the tool computes what it would write and returns a diff instead of touching any files:

{
  "dryRun": true,
  "wouldChange": [
    {
      "file": "System.json",
      "changed": true,
      "diff": {
        "changes": [{ "path": "gameTitle", "from": "Old Title", "to": "New Title" }],
        "truncated": false
      }
    }
  ],
  "wouldReturn": { "...": "what the tool would have returned, warnings included" }
}

wouldReturn carries the response the tool would have produced, so a dry-run also previews the validation warnings a write would have reported — not just the diff.

All writes go through a single choke point that skips no-op writes and keeps the on-disk JSON in the editor’s compact single-line format. File deletions (e.g. delete_map) share the same dry-run machinery.

Quiet write echoes

A write tool that echoes the whole record back costs the one caller that always pays for it — an AI assistant, whose context is the scarce resource. So the tools that would otherwise replay a command list or a map’s events return a summary by default:

The rule: keep what you would assert on, drop what you would only re-read. Command codes stay, because they are how you verify a splice landed where you asked (is the 302 still after the two 101s); command parameters go, because they are what you just wrote.

Pass verbose: true on any of those calls for the old full record, or read it back with get_map / get_map_event / get_database. warnings always survive summarization, and a dry-run’s wouldReturn is summarized the same way so a preview and the real call report the same shape.

Measured on six calls from one real authoring session: 115,080 → 3,672 characters (-97%). A single update_map that set a map’s BGM was echoing 46,846 characters of dialogue back at the caller.

Custom-tileset catalog skill

The default tilesets are cataloged out of the box. A non-default sheet that ships an RPG Maker .txt name sidecar next to it (img/tilesets/.txt, one Name|日本語名 line per tile — commercial DLC packs include these) is cataloged automatically too: its names come back with source: 'sidecar', no catalog files needed. Precedence per tile: a human-verified (manual) data/tilecatalog/ entry > the sidecar > a vision draft. For a custom (non-RTP) tileset with no sidecar, a bundled Claude skill under .claude/skills/tileset-catalog/ slices each sheet into labelled samples, has Claude vision-name them, and writes a versioned, project-scoped catalog to data/tilecatalog/ — after which find_tile/get_tile_catalog resolve names for that sheet too. Those drafts also record what each tile looks like, so find_tile with searchDescriptions: true can match that text when a machine-drafted name is too terse to search by. The skill ships a dependency-free PNG codec and engine-exact tile geometry, so it runs anywhere Node does.

Example prompts

Once configured, drive your project in natural language:

• “Create a fire skill ‘Fireball’ costing 15 MP that deals a.mat * 4 - b.mdf * 2 to one enemy.”
• “Add a new town map under the world map, 30×25, using the Outside tileset.”
• “Paint grass in a 10×8 rectangle at (4, 4) on map 3 and let it auto-border.”
• “Place a talking NPC named ‘Guard’ at (8, 5) on map 2 who says ‘Halt! Who goes there?’”
• “Make the water tiles on tileset 1 impassable and tag them terrain 1.”
• “Check my project for broken references before I ship.”

Development

npm run build         # Compile TypeScript to dist/
npm run typecheck     # Type-check without emitting (tsc --noEmit)
npm run dev           # Compile in watch mode
npm run lint          # ESLint
npm run lint:fix      # ESLint with autofix
npm run format        # Format with Prettier
npm run format:check  # Check formatting (used in CI)
npm test              # Vitest
npm run sync:tools    # Re-stamp the tool count into the README + SVGs (see below)
npm run sync:version  # Re-stamp package.json's version into the packaging manifests
npm run bundle:mcpb   # Build the one-click Claude Desktop bundle (rpgmaker-mz-mcp.mcpb)

During development you can skip the build entirely by running the server from source with tsx: point your MCP client’s command at node_modules/.bin/tsx with src/index.ts as the argument. Since tsx doesn’t type-check, run npm run typecheck alongside lint and tests before committing.

CI runs lint, format check, tool-count sync check, tests, and build on every push and pull request (see .github/workflows/ci.yml).

Keeping the tool count in sync

The advertised tool count lives in a few human-facing spots — the README prose and badge, and the two SVGs in assets/. npm run sync:tools counts the real tools from src/tools/ and re-stamps all of them, so bumping the number after adding a tool is one command. npm run sync:tools:check (run in CI) fails if any spot is stale.

Releasing

package.json is the source of truth for the version; npm run sync:version stamps it into the plugin manifest (.claude-plugin/plugin.json), the MCP-registry metadata (server.json), and the MCPB manifest (mcpb/manifest.json). CI and prepublishOnly fail if they drift. A release is:

npm version minor --no-git-tag-version   # or patch/major — bumps package.json only
npm run sync:version                     # stamp it into the other three manifests
git commit -am vX.Y.Z                    # one commit, with every manifest already correct
git tag vX.Y.Z                           # tag it afterwards, so nothing rewrites it
git push && git push origin vX.Y.Z

npm publish                 # publish to npm (runs the full gate via prepublishOnly)
mcp-publisher publish       # update the MCP registry listing (server.json; login: mcp-publisher login github)
npm run bundle:mcpb         # build rpgmaker-mz-mcp.mcpb
gh release create vX.Y.Z rpgmaker-mz-mcp.mcpb --title vX.Y.Z --notes "..."   # publish the GitHub release + attach the bundle

The Claude Code plugin needs no separate publish — users’ installs update from this repo (the plugin runs the npm package via npx rpgmaker-mz-mcp@latest, so bumping npm is what ships new tools).

Tag last, and never amend a tagged commit. npm version on its own commits and tags before sync:version has stamped the other manifests, so the old recipe amended afterwards — which left the tag pointing at the pre-amend commit, with stale manifests and off the branch entirely. --no-git-tag-version avoids the whole problem: one commit, then the tag. Push the tag by name (--follow-tags is easy to get wrong here), and don’t skip gh release create — nothing before it creates the GitHub release.

Project structure

rpgmaker-mz-mcp/
├── src/
│   ├── index.ts              # McpServer bootstrap: registers every tool, dispatch + dry-run
│   ├── registry.ts           # ToolDefinition shape + shared dryRun schema
│   ├── tools/                # One module per area (actors, items, skills, maps, battle,
│   │                         #   classes, states, common events, moves, plugins, tiles,
│   │                         #   catalog, paint, objects, tilesets, system, assets,
│   │                         #   event-command builders, event pages, list, validation)
│   ├── events/               # Pure event-command builders (no I/O)
│   ├── tiles/                # Tile subsystem: codec, autotile solver, paint core,
│   │                         #   flag codec, and the semantic catalog
│   ├── playtest/             # Headless engine driver: Chromium discovery, static server,
│   │                         #   render_map + run_playtest (optional playwright-core)
│   ├── validation/           # Known-command tables + event/move/plugin/reference validators
│   └── utils/                # File I/O, the commit choke point, and RPG Maker MZ types
├── test/                     # Vitest suite
├── scripts/
│   └── sync-tool-count.mjs   # Re-stamps the tool count into the README + SVGs
├── assets/                   # Banner + architecture SVGs
├── .claude/skills/
│   └── tileset-catalog/      # Vision catalog-bootstrap skill for custom tilesets
├── dist/                     # Compiled JavaScript (gitignored)
└── README.md

Safety and best practices

1. Close the RPG Maker MZ editor while using this server — it writes JSON files directly, and the editor can overwrite changes on save.
2. Use version control for your project. Combined with dry-run previews and validation, git is the safety net (the server does not make automatic backups).
3. Preview destructive edits with dryRun: true before committing them.
4. Test in-engine after significant changes.

Limitations

• Writes JSON files directly; the editor must be closed to avoid conflicts.
• Plugin commands are validated against the plugins your project actually ships (scan_plugins parses their @command/@arg annotations), falling back to a small built-in allowlist. Since RPG Maker MZ has no “required argument” annotation, scanned args are checked for unknown names only, never for missing ones; a plugin with no annotation block passes through unchecked.
• Animations (Animations.json, Effekseer-based) are not edited by this server.

Acknowledgements

This project started life as a fork of k4zuki0539/-rpgmaker-mz-mcp (MIT), which provided the original CRUD scaffolding. It has since grown well beyond that starting point — into full vanilla level-design and game-logic authoring (see Capabilities) — and is now maintained as its own project. Thanks to the original author for the foundation.

License

MIT

Resources

• RPG Maker MZ Official Website
• Model Context Protocol Documentation
• RPG Maker MZ Database Structure