# io.github.Xerolo44/rpgmaker-mv-mcp (npm · @xerolo44/rpgmaker-mv-mcp)

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

- Trust score: 69/100 (medium)
- Change this week: +25
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-05

## Components

- npm · `@xerolo44/rpgmaker-mv-mcp`: 69/100 (this document), [markdown](https://verifymcp.io/servers/xerolo44-rpgmaker-mv-mcp/xerolo44-rpgmaker-mv-mcp.md), [page](https://verifymcp.io/servers/xerolo44-rpgmaker-mv-mcp/xerolo44-rpgmaker-mv-mcp)

## Channel facts

- Registry: `npm`
- Package: `@xerolo44/rpgmaker-mv-mcp`
- Version: `0.1.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-05.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (118 of 122), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (118 of 122), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 17 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 77/100
  - AI-judged instruction clarity (excellent).
  - Tool/resource definitions use about 3836 tokens (~93/item across 41 items; 41 tools + 0 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 33/100
  - Stability observed for 10 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 85/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 56% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add xerolo44-rpgmaker-mv-mcp -- npx -y @xerolo44/rpgmaker-mv-mcp
```

### Codex

```bash
codex mcp add xerolo44-rpgmaker-mv-mcp -- npx -y @xerolo44/rpgmaker-mv-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "xerolo44-rpgmaker-mv-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@xerolo44/rpgmaker-mv-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add xerolo44-rpgmaker-mv-mcp --command npx --arg -y --arg @xerolo44/rpgmaker-mv-mcp
```

### Hermes

```yaml
mcp_servers:
  xerolo44-rpgmaker-mv-mcp:
    command: "npx"
    args: ["-y", "@xerolo44/rpgmaker-mv-mcp"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-04 (score 69, +5)

- [functional improvement] Stability: unverified → 0.30

### 2026-08-02 (score 64, +59)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Tool coverage: unverified → 100
- [functional] Licence: MIT

### 2026-08-01 (score 5, −21)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 26, −18)

- [security regression] Malware scan: pass → unverified

### 2026-07-27 (score 44)

First indexed and scored.

## MCP tools (41)

### `set_project` (~61 tokens)

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.

Input parameters:

- `path` (string, required): Absolute path to the RPG Maker MV project folder

### `get_project_info` (~29 tokens)

Get project info

Summary of the current project: game title, database record counts, map count, and plugin count.

### `list_records` (~55 tokens)

List database records

List all records of a database type as {id, name} summaries. Use get_record for full data.

Input parameters:

- `type` (string, required): Which database to access (e.g. actors, items, skills, troops, commonEvents)

### `get_record` (~56 tokens)

Get database record

Get the full JSON of one database record by id.

Input parameters:

- `id` (integer, required): Record id (1-based)
- `type` (string, required): Which database to access (e.g. actors, items, skills, troops, commonEvents)

### `update_record` (~121 tokens)

Update database 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.

Input parameters:

- `data` (object, required): Fields to set (or the complete record when merge=false)
- `id` (integer, required): Record id (1-based)
- `merge` (boolean): Merge into existing record (true) or replace (false)
- `type` (string, required): Which database to access (e.g. actors, items, skills, troops, commonEvents)

### `create_record` (~96 tokens)

Create database 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.

Input parameters:

- `data` (object, required): The record fields (id is assigned automatically)
- `type` (string, required): Which database to access (e.g. actors, items, skills, troops, commonEvents)

### `get_system` (~65 tokens)

Get System.json

Read System.json (game title, starting party/position, terms, sounds, switches, variables, etc.). Optionally return only one top-level key.

Input parameters:

- `key` (string): Optional top-level key to return (e.g. 'switches', 'variables', 'terms')

### `set_switch_name` (~64 tokens)

Name a switch

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.

Input parameters:

- `id` (integer, required): Switch id (1-based)
- `name` (string, required)

### `set_variable_name` (~64 tokens)

Name a variable

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.

Input parameters:

- `id` (integer, required): Variable id (1-based)
- `name` (string, required)

### `update_system` (~55 tokens)

Update System.json

Shallow-merge the given top-level fields into System.json (e.g. gameTitle, startMapId, startX, startY, switches, variables).

Input parameters:

- `data` (object, required): Top-level System.json fields to set

### `list_maps` (~26 tokens)

List maps

List all maps from MapInfos.json as {id, name, parentId, order}.

### `get_map` (~67 tokens)

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

Input parameters:

- `includeTileData` (boolean)
- `mapId` (integer, required)

### `update_map` (~76 tokens)

Update map properties

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.

Input parameters:

- `data` (object, required): Map property fields to set
- `mapId` (integer, required)

### `get_event` (~42 tokens)

Get map event

Get the full JSON of one event on a map, including all pages and command lists.

Input parameters:

- `eventId` (integer, required)
- `mapId` (integer, required)

### `update_event` (~85 tokens)

Update map 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.

Input parameters:

- `event` (object, required): Complete event object (name, x, y, note, pages)
- `eventId` (integer, required)
- `mapId` (integer, required)

### `create_event` (~100 tokens)

Create map 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.

Input parameters:

- `mapId` (integer, required)
- `name` (string, required)
- `note` (string)
- `pages` (array): Optional event pages; defaults to one empty page
- `x` (integer, required)
- `y` (integer, required)

### `delete_event` (~48 tokens)

Delete map event

Delete an event from a map. The slot is set to null so other event ids are unaffected (matches editor behavior).

Input parameters:

- `eventId` (integer, required)
- `mapId` (integer, required)

### `add_event_command` (~147 tokens)

Add event commands

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.

Input parameters:

- `commands` (array, required): Commands to insert, in order
- `eventId` (integer, required)
- `index` (integer): Position in the list to insert at; defaults to the end (before the terminator)
- `mapId` (integer, required)
- `pageIndex` (integer): Which event page (0-based)

### `add_dialogue` (~168 tokens)

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.

Input parameters:

- `background` (integer): 0 window, 1 dim, 2 transparent
- `eventId` (integer, required)
- `faceIndex` (integer)
- `faceName` (string): Face image file (e.g. 'Actor1'), empty for none
- `lines` (array, required): Dialogue lines (a new message box starts every 4 lines)
- `mapId` (integer, required)
- `pageIndex` (integer)
- `position` (integer): 0 top, 1 middle, 2 bottom

### `create_map` (~108 tokens)

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.

Input parameters:

- `height` (integer)
- `name` (string, required)
- `parentId` (integer): Parent map id in the editor tree (0 = top level)
- `tilesetId` (integer)
- `width` (integer)

### `event_command_reference` (~32 tokens)

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` (~21 tokens)

List plugins

List all plugins registered in js/plugins.js with status and parameters.

### `configure_plugin` (~78 tokens)

Configure plugin

Enable/disable a registered plugin and/or merge new values into its parameters (parameter values are always strings in RPG Maker MV).

Input parameters:

- `name` (string, required): Plugin name as it appears in list_plugins
- `parameters` (object): Parameter values to merge into the plugin's parameters
- `status` (boolean): true = enabled, false = disabled

### `add_plugin` (~69 tokens)

Register 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).

Input parameters:

- `description` (string)
- `name` (string, required)
- `parameters` (object)
- `status` (boolean)

### `remove_plugin` (~33 tokens)

Unregister plugin

Remove a plugin from js/plugins.js. The plugin's .js file is NOT deleted.

Input parameters:

- `name` (string, required)

### `create_plugin` (~94 tokens)

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.

Input parameters:

- `code` (string): Full JavaScript source; omit for a scaffold
- `description` (string)
- `name` (string, required): Plugin file name without .js
- `status` (boolean)

### `read_plugin` (~28 tokens)

Read plugin source

Read the JavaScript source of js/plugins/<name>.js.

Input parameters:

- `name` (string, required)

### `write_plugin` (~42 tokens)

Write plugin source

Overwrite the JavaScript source of an existing js/plugins/<name>.js.

Input parameters:

- `code` (string, required): Complete new file contents
- `name` (string, required)

### `playtest_start` (~159 tokens)

Start playtest

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.

Input parameters:

- `mode` (string)
- `port` (integer): Port for browser mode
- `runtimePath` (string): Path to NW.js executable. If omitted in nwjs mode, common install locations (Steam, KADOKAWA, the project's own Game.exe, $RPGMAKER_MV_NWJS) are probed automatically.

### `playtest_status` (~26 tokens)

Playtest status

Whether a playtest is running, in which mode, and its URL/PID.

### `playtest_log` (~35 tokens)

Playtest log

Recent stdout/stderr lines from an NW.js playtest process.

Input parameters:

- `tail` (integer): Number of lines from the end

### `playtest_stop` (~20 tokens)

Stop playtest

Stop the running playtest process and/or HTTP server.

### `create_damage_skill` (~375 tokens)

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.

Input parameters:

- `animationId` (integer): Animation id from the Animations database (0 = none, -1 = normal attack)
- `critical` (boolean): Can critically hit
- `damageType` (string): What the damage hits (drain variants absorb into the user)
- `description` (string): Two-line description shown in menus
- `elementId` (integer): Element id from System types (0 = none, -1 = normal attack element)
- `formula` (string, required): Damage formula, e.g. 'a.mat * 4 - b.mdf * 2'
- `hitType` (string): Hit type (affects evasion/reflection rules)
- `iconIndex` (integer): Icon sheet index
- `mpCost` (integer)
- `name` (string, required)
- `note` (string)
- `occasion` (integer): When usable: 0 always, 1 battle only, 2 menu only, 3 never
- `scope` (integer): Target scope: 1 one enemy, 2 all enemies, 3-6 random enemies (1-4), 7 one ally, 8 all allies, 9 one dead ally, 10 all dead allies, 11 the user
- `stypeId` (integer): Skill type id (1 = Magic by default)
- `tpCost` (integer)
- `tpGain` (integer): TP the user gains on use
- `variance` (integer): Damage variance %

### `create_healing_skill` (~309 tokens)

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

Input parameters:

- `animationId` (integer): Animation id from the Animations database (0 = none, -1 = normal attack)
- `description` (string): Two-line description shown in menus
- `formula` (string, required): Recovery formula, e.g. 'a.mat * 2 + 200'
- `iconIndex` (integer): Icon sheet index
- `mpCost` (integer)
- `name` (string, required)
- `note` (string)
- `occasion` (integer): When usable: 0 always, 1 battle only, 2 menu only, 3 never
- `recoverType` (string)
- `removeStates` (array): State ids to remove from the target (100% chance), e.g. poison
- `scope` (integer): Target scope: 1 one enemy, 2 all enemies, 3-6 random enemies (1-4), 7 one ally, 8 all allies, 9 one dead ally, 10 all dead allies, 11 the user (default: one ally)
- `stypeId` (integer): Skill type id (1 = Magic by default)
- `tpCost` (integer)
- `variance` (integer)

### `create_buff_skill` (~290 tokens)

Create buff/debuff 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.

Input parameters:

- `animationId` (integer): Animation id from the Animations database (0 = none, -1 = normal attack)
- `buffs` (array): Buffs to add to the target
- `debuffs` (array): Debuffs to add to the target
- `description` (string): Two-line description shown in menus
- `iconIndex` (integer): Icon sheet index
- `mpCost` (integer)
- `name` (string, required)
- `note` (string)
- `occasion` (integer): When usable: 0 always, 1 battle only, 2 menu only, 3 never
- `scope` (integer): Target scope: 1 one enemy, 2 all enemies, 3-6 random enemies (1-4), 7 one ally, 8 all allies, 9 one dead ally, 10 all dead allies, 11 the user
- `stypeId` (integer): Skill type id (1 = Magic by default)
- `tpCost` (integer)

### `create_state_skill` (~261 tokens)

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

Input parameters:

- `action` (string)
- `animationId` (integer): Animation id from the Animations database (0 = none, -1 = normal attack)
- `description` (string): Two-line description shown in menus
- `iconIndex` (integer): Icon sheet index
- `mpCost` (integer)
- `name` (string, required)
- `note` (string)
- `occasion` (integer): When usable: 0 always, 1 battle only, 2 menu only, 3 never
- `scope` (integer): Target scope: 1 one enemy, 2 all enemies, 3-6 random enemies (1-4), 7 one ally, 8 all allies, 9 one dead ally, 10 all dead allies, 11 the user (default: one enemy for add, one ally for remove)
- `states` (array, required): States to add/remove
- `stypeId` (integer): Skill type id (1 = Magic by default)
- `tpCost` (integer)

### `search_records` (~84 tokens)

Search database 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.

Input parameters:

- `limit` (integer)
- `query` (string, required)
- `type` (string): Database to search; omit to search all databases

### `search_map_events` (~123 tokens)

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}.

Input parameters:

- `limit` (integer)
- `mapId` (integer): Search only this map; omit for all maps
- `query` (string, required)
- `searchCommands` (boolean): Also search inside event command lists (slower, finds text/script content)

### `list_backups` (~50 tokens)

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` (~106 tokens)

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.

Input parameters:

- `file` (string): Project-relative file to restore; omit to restore all files in the session
- `session` (string): Backup session name from list_backups; defaults to the most recent

### `validate_project` (~68 tokens)

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

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/xerolo44-rpgmaker-mv-mcp/xerolo44-rpgmaker-mv-mcp#diagnostics

## Score history

- 2026-08-05: 69
- 2026-08-04: 69
- 2026-08-03: 64
- 2026-08-02: 64
- 2026-08-01: 5
- 2026-07-31: 26
- 2026-07-29: 44
- 2026-07-28: 44
- 2026-07-27: 44

## Links

- npm package: https://www.npmjs.com/package/@xerolo44/rpgmaker-mv-mcp
- Socket report: https://socket.dev/npm/package/@xerolo44/rpgmaker-mv-mcp
- Repository: https://github.com/Xerolo44/RPG-Maker-MV-MCP
- Changelog RSS feed: https://verifymcp.io/servers/xerolo44-rpgmaker-mv-mcp/xerolo44-rpgmaker-mv-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/xerolo44-rpgmaker-mv-mcp/xerolo44-rpgmaker-mv-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/xerolo44-rpgmaker-mv-mcp/xerolo44-rpgmaker-mv-mcp