# rpgmaker-mv-mcp [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/Xerolo44/RPG-Maker-MV-MCP  
**GitHub Stars:** 10  
**npm Downloads (last month):** 1304  
**Views:** 10  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/rpgmaker-mv-mcp

## Description
MCP server for reading, editing, and playtesting RPG Maker MV projects

## Tools
Capabilities this server exposes over MCP:

- **set_project** — Select the RPG Maker MV project folder to work on (the folder containing Game.rpgproject and data/). Must be called before other tools unless the server was started with --project.
- **get_project_info** — Summary of the current project: game title, database record counts, map count, and plugin count.
- **list_records** — List all records of a database type as {id, name} summaries. Use get_record for full data.
- **get_record** — Get the full JSON of one database record by id.
- **update_record** — Update a database record. By default the given fields are shallow-merged into the existing record; set merge=false to replace it entirely. The record's id always stays fixed to match its array position.
- **create_record** — Append a new record to a database. The new record's fields are copied from `data`; missing fields should be filled in to match the shape of existing records (fetch one with get_record as a template first). Returns the new id.
- **get_system** — Read System.json (game title, starting party/position, terms, sounds, switches, variables, etc.). Optionally return only one top-level key.
- **set_switch_name** — Set the editor name of a game switch in System.json (e.g. switch 5 = 'Opened Chest'). The switches array grows if the id is beyond its current size.
- **set_variable_name** — Set the editor name of a game variable in System.json (e.g. variable 3 = 'Quest Progress'). The variables array grows if the id is beyond its current size.
- **update_system** — Shallow-merge the given top-level fields into System.json (e.g. gameTitle, startMapId, startX, startY, switches, variables).
- **list_maps** — List all maps from MapInfos.json as {id, name, parentId, order}.
- **get_map** — Read a map's properties (size, tileset, music, encounters, notes) and event summaries. Tile data is omitted unless includeTileData=true (it is large: width*height*6 integers).
- **update_map** — Shallow-merge fields into a map's JSON (e.g. displayName, note, bgm, encounterList). Refuses to touch 'data' or 'events' — use dedicated event tools; tile editing is not supported.
- **get_event** — Get the full JSON of one event on a map, including all pages and command lists.
- **update_event** — Replace an event on a map with the given event JSON (same shape as returned by get_event). The event's id and its array position stay in sync automatically. See event_command_reference for command codes.
- **create_event** — Add a new event to a map at (x, y). If no pages are given, a single empty page (action-button trigger, no commands) is created. Returns the new event id.
- **delete_event** — Delete an event from a map. The slot is set to null so other event ids are unaffected (matches editor behavior).
- **add_event_command** — Insert commands into an event page's command list without resending the whole event. Commands are inserted before the page's terminating {code: 0} entry (or at `index` if given). Multi-line constructs work naturally, e.g. Show Text is one code-101 command followed by code-401 commands. See event_command_reference for codes.
- **add_dialogue** — Add spoken dialogue to an event page in one call — builds the Show Text (101) and text-line (401) commands automatically, splitting into multiple message boxes every 4 lines. Inserted before the page's end, like add_event_command.
- **create_map** — Create a new blank map: writes MapXXX.json with empty tile data and registers it in MapInfos.json. Tiles must still be painted in the editor, but events, properties, and everything else can be edited here. Returns the new map id.
- **event_command_reference** — Reference table of RPG Maker MV event command codes and their parameters. Consult this before writing or editing event command lists.
- **list_plugins** — List all plugins registered in js/plugins.js with status and parameters.
- **configure_plugin** — Enable/disable a registered plugin and/or merge new values into its parameters (parameter values are always strings in RPG Maker MV).
- **add_plugin** — Register an existing js/plugins/<name>.js file in the plugin list. Fails if the file does not exist (use create_plugin to make a new one).
- **remove_plugin** — Remove a plugin from js/plugins.js. The plugin's .js file is NOT deleted.
- **create_plugin** — Create a new plugin file in js/plugins/ and register it. If no code is given, a standard MV plugin scaffold (with @plugindesc header) is written. Fails if the file already exists.
- **read_plugin** — Read the JavaScript source of js/plugins/<name>.js.
- **write_plugin** — Overwrite the JavaScript source of an existing js/plugins/<name>.js.
- **playtest_start** — Start a playtest of the current project. mode 'nwjs' launches the game with an NW.js runtime (pass runtimePath, e.g. the Game.exe inside the RPG Maker MV install's nwjs-win folder) and captures its stdout/stderr. mode 'browser' serves the project over a local HTTP server and returns a URL to open. Any previous playtest is stopped first.
- **playtest_status** — Whether a playtest is running, in which mode, and its URL/PID.
- **playtest_log** — Recent stdout/stderr lines from an NW.js playtest process.
- **playtest_stop** — Stop the running playtest process and/or HTTP server.
- **create_damage_skill** — Create a complete damaging skill in one call. The formula uses MV damage syntax where `a` is the user and `b` the target, e.g. 'a.mat * 4 - b.mdf * 2' or 'a.atk * 2 - b.def'. Returns the new skill id.
- **create_healing_skill** — Create a complete healing skill in one call. The formula uses MV damage syntax (`a` = user), e.g. 'a.mat * 2 + 200'. Heals HP or MP; optionally also removes states (e.g. a cure spell).
- **create_buff_skill** — Create a skill that applies parameter buffs and/or debuffs. Parameter ids: 0 Max HP, 1 Max MP, 2 Attack, 3 Defense, 4 M.Attack, 5 M.Defense, 6 Agility, 7 Luck. If only debuffs are given the scope defaults to one enemy, otherwise one ally.
- **create_state_skill** — Create a skill that adds or removes states (poison, sleep, etc.) on the target, each with its own success chance. State ids come from the States database (list_records type=states).
- **search_records** — Case-insensitive substring search across database records (name, nickname, description, note, profile, messages). Searches one type, or all types when type is omitted. Returns {type, id, name, matchedIn} summaries.
- **search_map_events** — Case-insensitive substring search across events on one map or every map. Matches event names and notes; with searchCommands=true it also searches inside event command parameters (message text, script lines, plugin commands). Returns {mapId, mapName, eventId, name, x, y, matchedIn}.
- **list_backups** — List automatic backup sessions in <project>/.mcp-backups. A file is snapshotted there the first time each server session modifies it, so every session can be rolled back with restore_backup.
- **restore_backup** — Restore project files from a backup session (see list_backups). Restores one file (project-relative path like 'data/Actors.json') or, with no file given, every file in the session. The current state is itself backed up first, so a restore can be undone.
- **validate_project** — Integrity check of the whole project: parses every database file, verifies MapInfos entries have map files (and finds orphaned map files), checks registered plugins have source files, and scans event commands for references to missing common events or transfer destinations. Returns errors (broken) and warnings (suspicious).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "rpgmaker-mv-mcp": {
    "command": "npx",
    "args": ["-y","@xerolo44/rpgmaker-mv-mcp"]
  }
}
```

## Documentation

## What rpgmaker-mv-mcp does

rpgmaker-mv-mcp gives MCP clients structured access to RPG Maker MV projects. It can inspect project metadata, database records, system settings, maps, events, plugins, and registered assets. Editing tools cover record creation and updates, event authoring, dialogue insertion, map properties, plugin source, and project system data.

The server also includes higher-level workflows for common game-development tasks. These include skill creation, bulk database changes, stat-curve generation, localization import and export, map generation, reusable map stamps, asset inspection, event templates, dialogue trees, reference checks, progression analysis, event linting, and battle simulation.

## How it works

A project is selected with `set_project`, which expects the folder containing `Game.rpgproject` and `data/`, unless the server starts with `--project`. Database records are addressed by type and numeric ID. Existing records can be shallow-merged or fully replaced, while new records are appended and receive an ID based on their array position.

Maps and events are edited through dedicated tools. Events can be created, replaced, deleted, or modified by inserting commands into a page. `add_dialogue` builds Show Text commands and splits longer dialogue into additional message boxes. The event command reference provides the codes and parameters needed for lower-level event edits.

Before modifying files, the server snapshots each file touched during a session in `.mcp-backups/`. Project validation, backup restoration, dry-run diffs, and changesets provide additional ways to review or undo edits.

## Setup and configuration

Install the package globally with npm:

```sh
npm install -g @xerolo44/rpgmaker-mv-mcp
```

The package requires Node.js 18 or newer. For Claude Code, register it with the project path:

```sh
claude mcp add rpgmaker-mv -- npx @xerolo44/rpgmaker-mv-mcp --project "/path/to/YourGame"
```

Claude Desktop uses the same command and arguments in its `claude_desktop_config.json` MCP server entry. The `--project` argument is optional; without it, call `set_project` before using project tools.

An experimental HTTPS mode is available with `node dist/index.js --http [port]`. It exposes a localhost-only Streamable HTTP endpoint at `/mcp`, uses a cached self-signed certificate, and requires the process to remain running. Client support for self-signed localhost certificates varies, so stdio is the documented choice for Claude Code and Claude Desktop.

## Tools and capabilities

- Inspect project information, database records, system settings, maps, events, and plugins.
- Create, update, and delete database entries, maps, events, dialogue, switches, variables, and map properties.
- Add, configure, remove, read, write, and scaffold RPG Maker MV plugins.
- Search database content and event command lists across maps.
- Build skills, dialogue trees, event templates, map connections, generated maps, and reusable map stamps.
- Import, export, preview, and audit assets and localized game text.
- Validate references, lint events, simulate events and battles, analyze progression, and produce balance reports.
- Start NW.js or browser playtests and inspect playtest status.

## Limitations and notes

Tile editing is not supported by the basic map update tool, although the broader toolset includes map-painting and generation workflows. `get_map` omits tile data unless explicitly requested because the data is large. Deleting an event leaves its array slot as `null` so other event IDs remain unchanged.

NW.js playtests require a runtime path when automatic discovery is not suitable. Browser playtests return a local URL to open. HTTPS connector use may fail when a client rejects the generated self-signed certificate. Plugin parameter values are handled as strings, matching RPG Maker MV’s plugin format.

_Full upstream README: https://allmcps.com/mcp/rpgmaker-mv-mcp/readme_