Rpgmaker Mz MCP

RPG Maker MZ MCP Server

128 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

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

Expand the full tool reference

Project targeting

• get_project — the project the server is operating on: path, validity, game title
• set_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_class
• add_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 — every Skills.json field incl. occasion, hitType, speed, repeats, successRate, tpGain, required weapon types, message2, note; hitType defaults to magical for Magic skills, physical for other damage, certain for heals/ally scopes), update_skill, search_skills
• create_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_items
• create_weapon, update_weapon
• create_armor, update_armor

States

• create_state, update_state

Enemies & troops

• create_enemy, update_enemy, search_enemies
• create_troop, update_troop, search_troops — create_troop validates that every member references an existing enemy
• build_troop_page — build a battle-event page { conditions, list, span } from a compact trigger (when: turn [a, b], enemyHpBelow [slot, pct], actorHpBelow [actorId, pct], switch, turnEnd — ANDed) and a span (battle / turn / moment), no hand-built 12-field conditions object. Read-only
• add_troop_page — append (or insert at position) one page to a troop without re-sending the others; warns on an HP condition pointing past the troop's members

Common events

• create_common_event, update_common_event
• call_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_map
• get_map_region — read a window of tile ids (x, y, width, height, layer) instead of the whole map
• create_map — allocates the next id, writes a blank map, and registers it in the tree
• delete_map — removes a map and reparents its children onto its parent
• update_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_events
• create_map_event, update_map_event, delete_map_event
• add_event_command — append a single command to an event page
• set_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 (optionally auto word-wrapped with wrap) or explicit commands
• create_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_co