# rpgmaker-mz-mcp

An MCP server that lets an AI assistant change an RPG Maker MZ project: database records, maps, tiles, events. Useful when clicking through the editor gets old.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 24
- Author: Redseb
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Redseb/rpgmaker-mz-mcp
- Updated: 2026-09-25
- HTML: https://affpapa.org/en/nevibecode/mcp/rpgmaker-mz-mcp

## What it does

The server exposes the project's data files to the assistant: actors, classes, skills, items, equipment, states, enemies and troops, common events, maps with tilesets and tiles, system settings. A record needs only a name to exist; the remaining fields come from the editor's own template. Fresh maps get registered in `MapInfos.json` the way the engine expects.

Tile work is largely automatic. `paint_tiles` and `fill_area` place tiles across the six map layers and recompute autotile shapes from neighbours, so a filled region closes its own borders. `paint_blueprint` fills an area from ASCII rows plus a legend, and `place_object` stamps multi-cell B/C objects and reports their passability footprint. Tiles can be looked up by word: `find_tile "grass"` returns a usable id from the built-in catalogs covering the default tilesets. Before launching the game you can look at the build: `render_map` draws a map the way the engine does, and `run_playtest` drives a scripted headless session.

Set the project path in `RPGMAKER_PROJECT_PATH` first. It has to point at a folder holding `game.rmmzproject` and a `data/` directory with `System.json`; without it the server has nothing to open. Inputs are schema-checked, and a structurally broken event write is refused instead of saved with a warning.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `RPGMAKER_PROJECT_PATH` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env RPGMAKER_PROJECT_PATH=<RPGMAKER_PROJECT_PATH> --transport stdio rpgmaker-mz-mcp -- npx -y rpgmaker-mz-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add rpgmaker-mz-mcp --env RPGMAKER_PROJECT_PATH=<RPGMAKER_PROJECT_PATH> -- npx -y rpgmaker-mz-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "rpgmaker-mz-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "rpgmaker-mz-mcp"
            ],
            "env": {
                "RPGMAKER_PROJECT_PATH": "<RPGMAKER_PROJECT_PATH>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "rpgmaker-mz-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "rpgmaker-mz-mcp"
            ],
            "env": {
                "RPGMAKER_PROJECT_PATH": "<RPGMAKER_PROJECT_PATH>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e RPGMAKER_PROJECT_PATH=<RPGMAKER_PROJECT_PATH> rpgmaker-mz-mcp npx -y rpgmaker-mz-mcp
```
Replace <…> with your own values

## When to use it
- add new enemies and items to the database without opening the editor
- fill a map patch with grass and keep autotile edges correct
- drop a house or tree and check that passability still works
- build a branching dialogue with player choices onto an event page
- screenshot a map and run a scripted playtest before shipping the build

## Example prompts
- Find the grass tile and fill the area south of the town on `Map003`
- Add a potion seller in a new room under the world map
- Run `validate_references` and list every broken reference

## Similar
- [Pascal 3D Editor](https://affpapa.org/en/nevibecode/mcp/pascal-3d-editor.md) — MCP server · ★ 25085
- [Unity-MCP](https://affpapa.org/en/nevibecode/mcp/unity-mcp.md) — MCP server · ★ 4523
- [mcp](https://affpapa.org/en/nevibecode/mcp/sceneview-mcp.md) — MCP server · ★ 1348
- [Gearboy MCP Server](https://affpapa.org/en/nevibecode/mcp/gearboy-mcp-server.md) — MCP server · ★ 1219
- [ChiR24-unreal_mcp_server](https://affpapa.org/en/nevibecode/mcp/chir24-unreal-mcp-server.md) — MCP server · ★ 975
- [Nova3D](https://affpapa.org/en/nevibecode/mcp/nova3d.md) — MCP server · ★ 733

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md