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