RPG Maker MZ MCP Server
113 tools that let an AI assistant read and write an RPG Maker MZ project directly — actors, classes, skills, items, equipment, states, enemies, troops, common events, maps, tiles, tilesets, events, and system settings — instead of hand-editing everything in the editor.
"Add a town under the world map, paint it with grass, and drop in a shopkeeper who sells potions" → done, in-project, no editor clicks.
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
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. 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.
- 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:
export RPGMAKER_PROJECT_PATH=/path/to/your/rpgmaker/project
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
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.)
All 113 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).
Expand the full tool reference
Project targeting
get_project — the project the server is operating on: path, validity, game titleset_project — retarget the server at another project directory for the rest of the session (no restart; overrides RPGMAKER_PROJECT_PATH)
Actors
create_actor, update_actor, search_actors
Classes
create_class, update_classadd_class_learning — attach a skill learned at a level (validates the skill, keeps learnings level-sorted)set_class_param_curve — replace one of the 8 parameter growth rows
Skills
create_skill (full control), update_skill, search_skillscreate_damage_skill, create_healing_skill, create_buff_skill, create_state_skill — natural-language-friendly helpers for common skill types
Items & equipment
create_item, update_item, search_itemscreate_weapon, update_weaponcreate_armor, update_armor
States
create_state, update_state
Enemies & troops
create_enemy, update_enemycreate_troop, update_troop — create_troop validates that every member references an existing enemy
Common events
create_common_event, update_common_eventcall_common_event — builds the code-117 call command and validates the target exists
Maps & the map tree
get_map (pass includeData: false to omit the tile array on a big map), get_map_infos, get_map_dimensions, update_mapget_map_region — read a window of tile ids (x, y, width, height, layer) instead of the whole mapcreate_map — allocates the next id, writes a blank map, and registers it in the treedelete_map — removes a map and reparents its children onto its parentupdate_map_tree — batch reparent/reorder/rename/expand with an up-front existence check and cycle guard
Map events
get_map_events, get_map_event, search_map_eventscreate_map_event, update_map_event, delete_map_eventadd_event_command — append a single command to an event pageset_map_tile — set a single raw tile id at (x, y) on a z-layer (no autotiling)
Event & NPC ergonomics
create_npc — one-shot "talking NPC": graphic + trigger + a talk list from text or explicit commandscreate_chest — one-shot treasure chest: the two-page self-switch idiom (give item/weapon/armor/gold, then never again)create_transfer — one-shot map transfer, in either working idiom: face a solid landmark (action_button) or step on a doormat (player_touch)set_event_page — merge a page's graphic + behavior (sprite, trigger, priority, movement, flags) in place
Event-command builders
Read-only builders that return editor-faithful EventCommand sequences; land them on a command list with insert_event_commands.
- Dialogue & flow:
build_show_text (101/401), build_show_choices (102/402–404), build_conditional_branch (111/411/412), build_flow_command (wait/exit/label/jump)
- Game state:
build_control_switch (121/123), build_control_variable (122), build_change_gold (125), build_change_items (126–128), build_change_party_member (129)
- Presentation & transitions:
build_transfer_player (201), build_play_audio (BGM/BGS/ME/SE), build_screen_effect (fade/tint/flash/shake), build_picture (show/erase), build_character_effect (animation/balloon)
- Scenes:
build_battle_processing (301), build_shop_processing (302/605), build_name_input (303), build_change_actor (HP/MP/state/recover/EXP/level, 311–316)
- Insertion:
insert_event_commands — splice a built sequence into a map event page (the default target), a common event body, or a troop battle-event page, then validate
Move routes
create_move_route — build a MoveRoute from a named pattern (patrol/approach/flee/wander/custom)set_movement_route — insert a forced Set Movement Route (code 205 + 505 continuation rows)
Plugin commands
scan_plugins — discover the plugin commands this project actually has, by parsing js/plugins/*.js annotations (+ enabled state from js/plugins.js)list_plugin_commands — view the known plugin commands (the project scan merged over a built-in allowlist)create_plugin_command — build a code-357 plugin command with normalized args
Tiles, catalog & painting
describe_tile — decode a raw tile id (sheet, autotile kind/shape, geometry)get_tile_catalog, find_tile — resolve human names ↔ paintable tile idspaint_tiles, fill_area — paint with automatic autotilingplace_object — stamp a multi-tile B/C object and report its passability footprint
Tileset flags (passability / terrain)
get_tile_flags — decode a tile's passability/star/ladder/bush/counter/damage/terrain-tagcheck_passability — the map-aware, layered answer for a cellset_tile_flags — edit a tile's flags (non-destructive merge; auto-applies to all 48 shape slots of an autotile kind)
Assets
list_assets — enumerate available asset basenames (characters, faces, tilesets, pictures, audio, …)
System & vocabulary
get_system, get_game_title, update_game_titleget_variables, set_variable_name, get_switches, set_switch_nameget_starting_position, update_starting_positionget_party, set_party — the starting party (set_party validates every actor id)get_terms, set_term — menu vocabularyget_types, set_type_name — element/skill/weapon/armor/equip type-name listsset_currency_unit
Batch creation
batch_create — create many records of one type (actors, items, weapons, armors, skills, enemies, states, classes) in a single call and a single file write; ids allocate sequentially, so a record can reference a sibling made earlier in the same batch
Index & validation
list_names — cheap { id, name } index for a table (actors, items, skills, maps, enemies, …)get_database — full records from one table (actors, classes, items, weapons, armors, skills, enemies, troops, states, common_events), or a single record by idvalidate_event, validate_project — event-command-shape validation (read-only)validate_references — cross-file id-integrity audit (party→actor, transfer→map, effect→state/skill/common-event, drops→item, map-tree cycles, …)
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, …). Findings come in two tiers, and the tier decides what happens to the write:
- Structural — a wrong parameter count for a known command, a list not terminated by the code-
0 end marker, a non-array parameters, 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. 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.
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.
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.
Custom-tileset catalog skill
The default tilesets are cataloged out of the box. For a custom (non-RTP) tileset, 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. 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
npm run typecheck
npm run dev
npm run lint
npm run lint:fix
npm run format
npm run format:check
npm test
npm run sync:tools
npm run sync:version
npm run bundle: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).
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
npm run sync:version
git add -A && git commit --amend --no-edit && git push --follow-tags
npm publish
mcp-publisher publish
npm run bundle:mcpb
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).
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
│ ├── 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
- Close the RPG Maker MZ editor while using this server — it writes JSON files directly, and the editor can overwrite changes on save.
- 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).
- Preview destructive edits with
dryRun: true before committing them.
- 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
