RPG Maker MZ

You can run RPG Maker MZ MCP Server to automate map creation, event placement, plugin configuration, and even test playthroughs of your RPG Maker MZ projects. This server lets you issue natural language prompts and have the AI translate them into concrete changes in your project, with built-in safety checks, automatic backups, and undo support so you can iterate confidently.

How to use

You interact with the MCP client to send requests to the server. Start by ensuring the MCP server is configured in your client, then use natural language prompts to ask the AI to analyze your project, modify maps and events, manage assets and plugins, and run automated playtests. The server handles ID assignment, asset references, and safe execution. You can ask it to create new maps, place dialogue, add choices, set up conditional branches, spawn actors or items, and run a test play to verify the results.

Key capabilities include automatic data handling and validation, automatic backups before writes, undo of the last change, and a security layer that restricts which scripts can run. When you request changes, you’ll receive confirmation messages and structured results showing what was added or updated. If you want to preview a change before applying it, request a dry-run mode where supported.

How to install

Prerequisites you need: Node.js and a compatible MCP client. Follow the concrete steps below to set up the MCP server integration in your environment.

## Google Antigravity setup (no local install required) 

1. Ensure you have a compatible MCP client configured to use Antigravity.
2. Add the server config to your MCP client so it can launch the MCP server when requested. The example configuration uses npx to fetch the MCP package on demand.

{ "mcpServers": { "rpg-maker-mz": { "command": "npx", "args": ["-y", "@rein634/rpg-maker-mz-mcp"] } } }

3. Restart the Antigravity client and refresh the MCP Servers list. You should see the server ready to accept requests.

4. Use the MCP client to start parsing your project and issue your first prompt, for example: “Parse this project and add a conversation event to map 1.”

Alternative: local project-local setup (requires a local node process)
1. Install the MCP package globally or locally in your project. The examples below show a local project setup that uses an absolute path to the MCP runner.

Local project setup (absolute path example)

1. Globally install the MCP package (optional):

npm install -g @rein634/rpg-maker-mz-mcp

2. In your project config, set a stdio MCP server using an absolute path to the runner:

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "node",
      "args": ["C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/@rein634/rpg-maker-mz-mcp/dist/index.js"]
    }
  }
}

3. Replace the path with your actual user folder and ensure you use forward slashes for Windows paths. Restart your MCP client and refresh the server list.

## Additional setup methods (project-local and alternatives)

If you prefer to run the MCP runner directly from your project, you can install the package in the project and reference the local binary. The following example shows a project-local setup using an index.js script.

Project-local setup (no global install required)

1. In your RPG Maker MZ project directory:

npm install -D @rein634/rpg-maker-mz-mcp

2. Add a local MCP configuration file (for example, mcp_config.json) with:

{
  "mcpServers": {
    "rpg-maker-mz": {
      "command": "node",
      "args": ["./node_modules/@rein634/rpg-maker-mz-mcp/dist/index.js"]
    }
  }
}

3. Restart your MCP client and refresh MCP Servers.

## Security and backups

All write operations trigger automatic backups before changes are committed. Backups are stored with a timestamp suffix and up to the latest five are kept. If an error occurs during a write, the system automatically rolls back to the previous backup.

A white-list based security model restricts executed code for sensitive tools. You can disable specific tools in client configuration if needed, but only trusted environments should enable such features.

## Common troubleshooting

If you encounter errors during configuration, ensure your JSON configuration is valid and free of comments or trailing commas. Use a JSON validator to confirm syntax, and verify that paths use forward slashes on Windows.

If you see EOF or startup errors with global wrappers, prefer Antigravity-based configuration or project-local setup as described above.

## Practical examples

Example 1: Create a new actor and add a dialogue event to map 1 event 1.

Example 1

add_actor({ projectPath: "C:/Games/MyProject", name: "新キャラ" }); add_dialogue({ projectPath: "C:/Games/MyProject", mapId: 1, eventId: 1, pageIndex: 0, insertPosition: -1, text: "こんにちは！\n新しい仲間です。" });

## Notes on reliability and scope

This server is designed for local development and experimentation. Exercise caution with production data and keep regular backups. Always validate changes with a test playthrough.

## Available tools

### get\_project\_info

Fetches project basic information from System.json such as title, version, and currency.

### list\_data\_files

Lists JSON data files under the data directory.

### read\_data\_file

Reads the content of a specified data file (e.g., Actors.json).

### write\_data\_file

Writes JSON content to a data file with automatic backup prior to writing.

### search\_events

Searches text or IDs within map and common events.

### get\_event\_page

Retrieves the command list for a specific event page with readable explanations for key commands.

### list\_assets

Lists asset files in img and audio directories.

### check\_assets\_integrity

Checks that referenced assets exist in the project.

### write\_plugin\_code

Creates a new plugin file under js/plugins with specified code.

### get\_plugins\_config

Reads current plugin configuration from js/plugins.js.

### update\_plugins\_config

Updates the plugin configuration in js/plugins.js.

### add\_dialogue

Adds a dialogue line to an event page.

### add\_choice

Adds a choice block to an event page with up to six options.

### add\_loop

Adds a loop structure to an event page.

### add\_break\_loop

Adds a command to break out of a loop.

### add\_conditional\_branch

Adds an If-Else-End conditional to an event page.

### delete\_event\_command

Deletes a specific event command by index.

### update\_event\_command

Updates a specific event command with new content.

### add\_actor

Adds a new actor to the database.

### add\_item

Adds a new item to the database.

### add\_skill

Adds a new skill to the database.

### draw\_map\_tile

Places a map tile at specified coordinates.

### create\_map

Creates a new map with given dimensions.

### show\_picture

Adds a picture display command to an event.

### inspect\_game\_state

Evaluates whitelisted JavaScript expressions against the running game state.

### run\_playtest

Launches a playtest, captures screenshots, and optionally uses a browser-based fallback.

### undo\_last\_change

Restores the most recent backup for a file.

### list\_backups

Lists backups for a specified file or all files.