rpgmaker-mz-mcp — Claude Code MCP server: edit RPG Maker MZ projects
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.
claude mcp add --env RPGMAKER_PROJECT_PATH=<RPGMAKER_PROJECT_PATH> --transport stdio rpgmaker-mz-mcp -- npx -y rpgmaker-mz-mcpWhat rpgmaker-mz-mcp 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.
What it helps with
- 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 for the agent
- 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_referencesand list every broken reference
How to install rpgmaker-mz-mcp
Platform CLI
claude mcp add --env RPGMAKER_PROJECT_PATH=<RPGMAKER_PROJECT_PATH> --transport stdio rpgmaker-mz-mcp -- npx -y rpgmaker-mz-mcpReplace <…> with your own values
Platform CLI
codex mcp add rpgmaker-mz-mcp --env RPGMAKER_PROJECT_PATH=<RPGMAKER_PROJECT_PATH> -- npx -y rpgmaker-mz-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"rpgmaker-mz-mcp": {
"command": "npx",
"args": [
"-y",
"rpgmaker-mz-mcp"
],
"env": {
"RPGMAKER_PROJECT_PATH": "<RPGMAKER_PROJECT_PATH>"
}
}
}
}Replace <…> with your own values
Config file
{
"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
Platform CLI
gemini mcp add -e RPGMAKER_PROJECT_PATH=<RPGMAKER_PROJECT_PATH> rpgmaker-mz-mcp npx -y rpgmaker-mz-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about rpgmaker-mz-mcp
How to install rpgmaker-mz-mcp in Claude Code?
Two commands: claude mcp add rpgmaker-mz-mcp -- npx -y rpgmaker-mz-mcp, then claude mcp add --env RPGMAKER_PROJECT_PATH=<RPGMAKER_PROJECT_PATH> --transport stdio rpgmaker-mz-mcp -- npx -y rpgmaker-mz-mcp.
What does rpgmaker-mz-mcp do?
It hands an AI assistant tools to read and change data in an RPG Maker MZ project: database records, maps, tiles, events. It also validates writes and can render a map or run a playtest.
What does the server need to run?
A project path in RPGMAKER_PROJECT_PATH. That folder must contain game.rmmzproject and data/ with System.json.
