rpgmaker-mz-mcp

<div align="center">

<img src="assets/banner.svg" alt="RPG Maker MZ MCP Server" width="100%" />

# RPG Maker MZ MCP Server

[![CI](https://github.com/Redseb/rpgmaker-mz-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Redseb/rpgmaker-mz-mcp/actions/workflows/ci.yml)
[![Tools](https://img.shields.io/badge/tools-119-e94560.svg)](#available-tools)
[![MCP](https://img.shields.io/badge/MCP-stdio-e94560.svg)](https://modelcontextprotocol.io/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6.svg)](tsconfig.json)
[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-3fa796.svg)](package.json)
[![License: MIT](https://img.shields.io/badge/License-MIT-3fa796.svg)](#license)

**119 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.

</div>

## Quick start

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

```bash
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:

```json
{
  "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](https://github.com/Redseb/rpgmaker-mz-mcp/releases) and open it with Claude Desktop.

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

## Contents

- [Quick start](#quick-start)
- [Capabilities](#capabilities)
- [How it fits together](#how-it-fits-together)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Available tools](#available-tools)
- [Input validation](#input-validation)
- [Event validation (throw-by-default)](#event-validation-throw-by-default)
- [Reference linting](#reference-linting)
- [Dry-run preview](#dry-run-preview)
- [Custom-tileset catalog skill](#custom-tileset-catalog-skill)
- [Example prompts](#example-prompts)
- [Development](#development)
- [Project structure](#project-structure)
- [Safety and best practices](#safety-and-best-practices)
- [Limitations](#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. `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

<div align="center">
<img src="assets/architecture.svg" alt="AI assistant talks to the MCP server over stdio, which reads and writes the RPG Maker MZ project's data files" width="100%" />
</div>

## 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](#quick-start)). Tools only, no skills.
- **MCPB bundle (Claude Desktop)** — download `rpgmaker-mz-mcp.mcpb` from [Releases](https://github.com/Redseb/rpgmaker-mz-mcp/releases), open it with Claude Desktop, and pick your project folder in the install dialog.
- **From source** (development):

```bash
npm install
npm run build
```

## Configuration

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

```bash
# 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

```bash
npm start          # or: node dist/index.js
```

### Configuring in Claude Desktop

The easiest path is the `.mcpb` bundle from [Releases](https://github.com/Redseb/rpgmaker-mz-mcp/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):

```json
{
  "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 119 tools, grouped by area. Tools that write to the project accept an optional `dryRun` argument (see [Dry-run preview](#dry-run-preview)); those that can refuse a structurally invalid write also accept `force` (see [Event validation](#event-validation-throw-by-default)).

<details>
<summary><strong>Expand the full tool reference</strong></summary>

### 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), `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

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

#