Rpgmaker Mv Mcp

io.github.Xerolo44由 GitHub 账号 Xerolo44 发布v0.5.1更新于 Nov 1, 2026

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

概览

AI 生成的概览

让助手读取、编辑、绘制、渲染并试玩 RPG Maker MV 游戏项目,所有写入都配有备份与变更集。

可以做什么
  • 选择项目并查看标题、数据库记录数、地图与插件概况
  • 列出、读取、创建和更新数据库记录与 System.json,包括开关和变量命名及技能生成
  • 创建、编辑和删除地图与事件,插入事件指令与对话,查询指令代码
  • 查看图块集、绘制图块,把地图渲染为文本或 PNG,并对比版本差异
  • 搜索记录与事件,执行批量修改、平衡报告与战斗模拟,导出和导入文本
  • 管理插件、导入素材、启动和停止试玩,并校验项目或从备份恢复
适用场景
适合在制作或维护 RPG Maker MV 游戏时,让助手直接修改项目中的数据库、地图、事件、插件或数值平衡,并通过渲染地图或启动试玩来检查结果。
运行要求
以 npm 包形式通过 stdio 在本机运行,需要 Node.js 18 或更高版本。需指向包含 Game.rpgproject 和 data/ 的项目文件夹,可用 --project 参数指定,或先调用 set_project。未声明账号、API 密钥或环境变量;可用 --tools 或 RPGMV_TOOLS 限制注册的工具组。NW.js 试玩需要运行时路径,实验性 HTTPS 模式使用自签名的本机证书。
安装前请注意
工具会写入项目文件:记录、地图、事件、图块、插件、素材和文本都可能被创建、覆盖或删除,调用 set_project 会丢弃未提交的变更集。虽有备份和变更集,但 undo_changeset 会覆盖之后的修改,二进制素材导入无法暂存。运行期间应保持 RPG Maker 编辑器关闭。试玩模式会启动本地进程或 HTTP 服务器。批量修改和文本导入默认只做试运行,除非把 dryRun 设为 false。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Rpgmaker Mv Mcp,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

RPG Maker MV MCP Server

[CI] [License: MIT] [Node >= 18] [MCP] [Rpgmaker MV MCP on mcprush]

A Model Context Protocol server that turns AI assistants (Claude Code, Claude Desktop, or any MCP client) into a co-developer for RPG Maker MV projects — with automatic backups of everything it touches.

Ask your assistant things like:

"Create a Fireball skill: magical damage, a.mat * 4 - b.mdf * 2, 12 MP, fire element." "Find every event in the game that mentions the mayor." "Add a guard to the castle gate who says 'Halt! Who goes there?'" "Rebalance all weapons: +10% attack across the board." "Validate the project — anything broken?"

Highlights

  • Full database access — all 12 database types (actors, classes, skills, items, weapons, armors, enemies, troops, states, animations, tilesets, common events) plus System.json, through a compact generic CRUD interface.
  • High-level skill builders — create complete, editor-valid damage / healing / buff / state skills from just a name and a formula.
  • Maps and events — create maps, create/edit/delete events, insert event commands in batches, add dialogue with automatic message-box splitting, and consult a built-in event command code reference.
  • Tilesets and map painting — inspect a tileset (sheets, autotile kinds, passability), look at its sheet images, switch a map's tileset, and paint ground, water, walls and objects with rectangles, flood fill and single cells. Autotile edges and corners are computed exactly like the editor does, so painted maps look right in game. render_map shows the result as text.
  • See your maps — render_map_image renders a map to a PNG with the real tileset graphics, autotiles, shadows, event sprites, numbered event markers, region ids and an optional grid, so the assistant can look at what it built instead of working blind.
  • Map connector — connect_maps places Transfer Player doors on two maps in both directions in one call (with spawn tiles, fades and sounds); list_map_connections shows the map graph, one-way doors, broken targets and maps you cannot reach.
  • Bulk edits and balancing — bulk_update_records ("all weapons +10% attack") with a dry-run diff, generate_param_curve / generate_enemy_scaling for stat curves, balance_report (class curves, damage vs enemy HP, enemy threat) and simulate_battle (Monte-Carlo troop vs party using the real damage formulas).
  • Localization — export_texts / import_texts move every text of the game (database, system terms, map names, dialogue, choices, battle events) through CSV or JSON, keep control codes intact and split long dialogue into extra message boxes.
  • Skill files, prompts and resources — bundled SKILL.md workflow guides, reference tables as MCP resources and ready-made prompts (new_town, balance_check, ...), see Skills, prompts and resources.
  • Search everywhere — substring search across every database, and across every event on every map, including inside event command lists (find which event shows a line of dialogue or runs a script).
  • Plugin management — enable/disable/configure plugins, scaffold new ones, edit plugin source, all in the editor's own js/plugins.js format.
  • Playtest control — launch the game through NW.js (auto-detected from common install locations) with stdout/stderr capture, or serve it to a browser via the built-in HTTP server.
  • Authoring helpers — build_dialogue_tree compiles nested dialogue and choices, cutscene effects (fades, audio, pictures, move routes, ...) and game-flow commands (battles, shops, items, party, scenes, ...) into correctly indented event commands, create_event_from_template builds chests, locked doors, inns, shops, save points and NPCs in one call. See Cutscene and game-flow nodes.
  • Assets — import_asset copies images and sounds into the project, list_assets shows what is there and what uses it, preview_asset lets the assistant look at an image. See Assets.
  • Map generation and stamps — generate_map makes seeded dungeons and caves with entrance/exit/chest markers; capture_stamp / place_stamp reuse a hand-built piece of map. See Map generation and stamps.
  • Analysis — audit_assets, lint_events and simulate_event check an event or the whole project without launching the game, see Analysis. find_usages shows everywhere an id is read, written or used, check_references finds references to records that do not exist, and analyze_progression asks which maps and events can ever be reached, see Usage and progression analysis.
  • Safety net — every file is snapshotted to .mcp-backups/ before its first modification each session; restore_backup rolls anything back, validate_project catches broken references before you ship, and changesets let you stage a batch of edits, commit it in one step and undo it.

Installation

Requires Node.js 18+.

Quick start (npm)

The easiest way for Claude Code or Claude Desktop users:

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

Then configure it (see below). The package is available on npmjs.com and in the MCP Registry.

Configure Claude Code

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

Configure Claude Desktop

Add to claude_desktop_config.json:

json
{  "mcpServers": {    "rpgmaker-mv": {      "command": "npx",      "args": [        "@xerolo44/rpgmaker-mv-mcp",        "--project", "/path/to/YourGame"      ]    }  }}

--project is optional — without it, ask the assistant to call set_project first. The project can also be switched mid-session.

Custom connector / URL-based clients (HTTPS) — experimental

Some clients (e.g. "Add custom connector" UIs) don't spawn a local process — they connect to a URL instead. Run the server in HTTPS mode:

sh
node dist/index.js --http [port]   # default port 3939

This starts a Streamable HTTP MCP endpoint at https://127.0.0.1:<port>/mcp, bound to localhost only (never reachable from the network — every request is checked against the connecting socket's address, not just the bind address). A self-signed TLS certificate for localhost/127.0.0.1 is generated on first run and cached in .certs/ (gitignored) next to the project.

Status: the endpoint is fully verified at the protocol level (handshake, session management, and the 41 tools of the first release tested directly over HTTPS with curl). What's not guaranteed is that a given GUI connector-adding flow will accept a self-signed localhost certificate — some do (after a manual "proceed anyway" warning, since they open the URL as a normal page), others silently reject it because their background connection check doesn't trust locally-generated certs and gives no user-facing error. If adding the connector spins and fails with no message, that's very likely what's happening, and it's a limitation of that client's trust handling, not of this server. The reliable, zero-friction way to use this server today is the stdio mode above (Claude Code CLI / Claude Desktop's local server config) — reach for --http only if your client specifically requires a URL.

The server process must stay running for the connector to work — start it in its own terminal window before adding the connector, and leave that window open.

Tool reference (78 tools)

GroupTools
Projectset_project, get_project_info
Databaselist_records, get_record, update_record, create_record, get_system, update_system, set_switch_name, set_variable_name
Skill helperscreate_damage_skill, create_healing_skill, create_buff_skill, create_state_skill
Searchsearch_records, search_map_events
Maps & eventslist_maps, get_map, create_map, update_map, get_event, update_event, create_event, delete_event, add_event_command, add_dialogue, event_command_reference
Authoringbuild_dialogue_tree, create_event_from_template
Tilesets & paintingget_tileset_info, get_tileset_image, set_map_tileset, paint_tiles, render_map, render_map_image, render_diff
Generationgenerate_map, capture_stamp, place_stamp, list_stamps
Map connectionsconnect_maps, list_map_connections
Bulk & balancingbulk_update_records, generate_param_curve, generate_enemy_scaling, balance_report, simulate_battle
Localizationexport_texts, import_texts
Skill filesinstall_skills
Pluginslist_plugins, configure_plugin, add_plugin, remove_plugin, create_plugin, read_plugin, write_plugin
Playtestplaytest_start, playtest_status, playtest_log, playtest_stop
Analysisaudit_assets, lint_events, simulate_event, find_usages, check_references, analyze_progression
Assetsimport_asset, list_assets, preview_asset
Safetylist_backups, restore_backup, validate_project, editor_status, begin_changeset, commit_changeset, discard_changeset, undo_changeset

Every tool description is written for AI consumption: parameter semantics, RPG Maker quirks (target scopes, command codes, 1-indexed arrays), and pointers to related tools are all in the schema, so assistants can use the server without external documentation.

Tool profiles

All 78 tools are registered by default. Some clients cope better with a shorter tool list, so you can register only some tool groups with --tools (a comma-separated list) or the environment variable RPGMV_TOOLS:

sh
claude mcp add rpgmaker-mv -- npx @xerolo44/rpgmaker-mv-mcp --project "/path/to/YourGame" --tools maps,tiles,render,authoring

Groups: project, database, maps, tiles, render, plugins, playtest, search, maintenance (backups, validation, editor_status and the changeset tools), connect, balance, localization, authoring, generation, analysis, assets. project (set_project, get_project_info) is always on, all (the default) enables everything, and an unknown group name makes the server exit with a message. install_skills, resources and prompts are always available whatever the profile.

Tools per group (77 tools, plus install_skills, which is always on = 78):

  • project (2): set_project, get_project_info
  • database (12): list_records, get_record, update_record, create_record, get_system, set_switch_name, set_variable_name, update_system, create_damage_skill, create_healing_skill, create_buff_skill, create_state_skill
  • maps (11): list_maps, get_map, update_map, get_event, update_event, create_event, delete_event, add_event_command, add_dialogue, create_map, event_command_reference
  • tiles (5): get_tileset_info, get_tileset_image, set_map_tileset, paint_tiles, render_map
  • render (2): render_map_image, render_diff
  • plugins (7): list_plugins, configure_plugin, add_plugin, remove_plugin, create_plugin, read_plugin, write_plugin
  • playtest (4): playtest_start, playtest_status, playtest_log, playtest_stop
  • search (2): search_records, search_map_events
  • maintenance (8): list_backups, restore_backup, editor_status, validate_project, begin_changeset, commit_changeset, discard_changeset, undo_changeset
  • connect (2): connect_maps, list_map_connections
  • balance (5): bulk_update_records, generate_param_curve, generate_enemy_scaling, balance_report, simulate_battle
  • localization (2): export_texts, import_texts
  • authoring (2): build_dialogue_tree, create_event_from_template
  • generation (4): generate_map, capture_stamp, place_stamp, list_stamps
  • analysis (6): audit_assets, lint_events, simulate_event, find_usages, check_references, analyze_progression
  • assets (3): import_asset, list_assets, preview_asset

Changesets (transactional edits with undo)

For a multi-step change, wrap it in a changeset instead of letting every call hit the disk:

  1. begin_changeset {label} — from now on every edit tool stages its result in memory. Reads (get_map, get_record, list_plugins, ...) see the staged edits, but nothing is on disk until you commit; a playtest only sees committed files.
  2. Make the edits as usual.
  3. commit_changeset writes every staged file in one step (staged .json files are validated first; if any is invalid nothing is written and the changeset stays open) and returns a per-file summary. Or discard_changeset to drop everything.
  4. undo_changeset rolls the most recent commit back from its journal in .mcp-backups/changesets/ (call it repeatedly to go further back). It restores the files as they were before that commit, so edits made to them since are overwritten too.

Only one changeset can be open at a time, restore_backup is refused while one is open and set_project discards it. If the process dies in the middle of a commit, the next time the project is opened the half-finished commit is rolled back (the files found on disk are backed up first) and set_project / editor_status report it. Keep the RPG Maker editor closed, as always.

Skills, prompts and resources

Besides tools, the server offers three kinds of built-in guidance that MCP clients can use:

Skill files (skills/<name>/SKILL.md) are short workflow guides for the assistant. They are served as resources (rpgmaker://skills/<name>) and can be copied into your game project with the install_skills tool, so Claude Code loads them automatically in that project (.claude/skills/, or scope: "user" for ~/.claude/skills/):

SkillCovers
rpgmaker-mv-workflowSafety rules, data conventions, which tool to use for what, assets and analysis before release
rpgmaker-map-buildingPlan → paint → look → fix loop, layers, tile choice, connecting maps
rpgmaker-event-writingDialogue, choices, indentation rules, switches, one-time chests, triggers
rpgmaker-balancingTargets, report/simulation workflow, curves, bulk edits with dry runs
rpgmaker-localizationExport/import workflow, control codes, message length
rpgmaker-plugin-devPlugin header, aliasing engine methods, plugin commands, testing

Resources — rpgmaker://reference/event-commands, trait-codes, damage-formulas and database-fields are the lookup tables an assistant needs most, available without a tool call.

Prompts — ready-made workflows that show up as commands in clients that support MCP prompts: new_town, design_dungeon, add_quest, balance_check, review_dialogue, translate_game and project_health.

Map generation and stamps

generate_map builds a dungeon (rooms joined by corridors) or a cave (one organic connected region) either into an existing empty map (mapId) or into a new one (create, which also registers it in MapInfos.json). It is deterministic: the same seed, size and options give the same layout, and the seed used is always returned. A map that already has tiles or events is refused unless you pass overwrite: true.

  • Tile profile. The map is painted with a profile (floor, wall, optional wallTop, optional weighted decor). If you give none, one is suggested from the tileset's own data (walkable A2 kind for the floor, blocking A4 wall kind for the wall) and returned as profileUsed / profileNotes. Nothing is written if the floor is not walkable, the wall does not block movement, or the result is not fully reachable from the entrance.
  • Markers. markers (default: entrance and exit, no chests) places empty events named Entrance, Exit and Chest 1..n at priority 0, so they never block the player. They are placeholders: wire the doors with connect_maps (pass allowOverlap, or delete_event the marker first) and fill the chests with create_event_from_template.
  • Sizes. Dungeons need at least 14x7 (or 7x14); caves are reliable from about 13x13 (MV's default 17x13 never failed in testing), while 9x9 to 12x12 and thin maps fail for many seeds; try another seed or a larger map.
  • Look at it. Use render_map_image (try showPassability) and render_diff. Wall faces are a one-row simplification and decor is sparse; see CHANGELOG.md for what has and has not been checked.

Stamps are reusable pieces of map. capture_stamp saves a rectangle (up to 64x64, all six layers and, by default, the events inside it) to <project>/.mcp-stamps/<name>.json; place_stamp pastes it with its top-left corner at (x, y) on a map that uses the same tileset and list_stamps shows what you have. Placement replaces the rectangle on every layer, re-shapes autotile edges against the surroundings and never clips; there is no rotate or mirror.

Assets

Three tools handle the project's image and sound files (img/* and audio/*, 18 folders):

  • import_asset {source, folder, name?, overwrite?} copies a file from your computer into <project>/<folder>/<name>.<ext>. source must be an absolute path to a regular file on a local drive (no relative paths, network shares, devices or symbolic links). The file type is read from the file's header only and must fit the folder: img/* takes files with a PNG signature and header, audio/* takes files that start with OggS (Ogg) or have an ftyp box (M4A). The extension is chosen from what the header says, never from the source name. Nothing is converted or resized, and the rest of the file is not checked. Size caps are 32 MiB for images and 128 MiB for audio.
  • list_assets {folder?, includeUsage?, limit?} lists the files of one or all folders with size, PNG dimensions, warnings (a header that does not match the extension, a sheet size that does not fit the folder, interlaced PNGs) and, for the folders the reference scan covers, usedBy and unused. Unused means no reference with exactly that name (case-sensitive) in the database, maps, common events or troops; a plugin or script that loads a file by name is not seen.
  • preview_asset {folder, name, maxSize?} returns a PNG from an img/* folder as an image (nearest-neighbour scaled to at most maxSize pixels on its longer edge), with the sheet layout implied by the name for img/characters and img/faces. Interlaced PNGs, files over 32 MiB and images above 16 million pixels are refused; audio cannot be previewed.

Name rules. A name is 1-64 characters from A-Z a-z 0-9 space _ ! $ ( ) -, starts with a letter, digit, ! or $, has no trailing space, no dot (the extension is added for you) and no path separators, and is not a reserved Windows device name (CON, NUL, COM1, LPT1, ...). In img/characters, a name whose leading run of ! and $ characters contains a $ ($Boss, !$Chest) is a one-character sheet; a ! means no vertical offset on the map.

Backups and changesets. An existing file with the same name (letter case ignored) is only replaced with overwrite: true. Like any other edit, the first change to a file in a server session snapshots it to .mcp-backups/ (list_backups, restore_backup), so the backup holds the file as it was before the session (until set_project is called again, which starts the snapshots over): a file that was created, or already replaced, earlier in the same server session has no backup of that intermediate version. Binary files cannot be staged, so import_asset is refused while a changeset is open; commit or discard it first. Nothing is written when an import is refused. For audio, a warning tells you when the .ogg or .m4a twin is missing (MV's web build needs both).

Cutscene and game-flow nodes

Besides dialogue, choices, conditions, switches, variables and transfers, build_dialogue_tree compiles these nodes into correctly indented commands. Like the MV editor, every choice, if/else and battle branch ends with a blank {code: 0} row at the body's indent (an empty branch is that row alone); the engine skips it.

  • Cutscene: wait, fade (out / in), tint, flash, shake, weather, playAudio, fadeAudio, showPicture, erasePicture, animation, balloon and moveRoute. A route is a list of steps (up, turnLeft, {wait: 10}, {jump: {x, y}}, {switchOn: 5}, {speed: 4}, ...); a repeating route (repeat: true) never finishes, so it cannot be waited for and an explicit wait: true is rejected.
  • Game flow: battle (onWin, onEscape and onLose bodies; like the editor, the branches and their closer are written only when canEscape or canLose is on, or onWin has nodes, and with neither the battle is a single command followed by whatever comes next; a body for a branch whose box is off is rejected), shop, callCommon, label / jump, exit, comment, gold, item (items, weapons and armors), party, learnSkill, recoverAll, nameInput, plugin (a plugin command line) and scene (menu, save, game over, title).

Example, as the tree argument (or with dryRun: true to only look at the commands):

json
[  { "fade": "out" },  { "battle": { "troopId": 3, "canLose": true,      "onWin": [{ "gold": 200 }],      "onLose": [{ "say": "Defeated..." }, { "scene": "gameOver" }] } },  { "fade": "in" },  { "shop": { "goods": [{ "type": "item", "id": 1 }, { "type": "weapon", "id": 2, "price": 300 }] } }]

simulate_event can dry-run the result: presentation commands are skipped and counted in cosmetic, and battleResult (win, escape or lose) chooses which battle branch runs. The command layouts were checked against the official MV core scripts, and the block and move-route structure against real map files from public MV projects, but nothing was run in the real game, so playtest important events; see CHANGELOG.md for the limitations.

Analysis

Checks that need no running game:

  • audit_assets — every image and audio file the project references (actors, enemies, tilesets, maps, event pages, a set of event commands (face, picture, audio, battle back, parallax, actor and vehicle graphics), System) must exist; also lists case mismatches (fine on Windows, broken on Linux/macOS/web) and optionally unused files. The result lists what is not scanned (for example plugin parameters), so "unused" can include files that only plugins use.
  • lint_events — static checks of event command lists in maps, common events and troops: broken block structure and terminators, unreachable commands, over-long message lines, transfers to missing maps or out-of-bounds tiles, calls to missing common events, and switches/variables without a name. Findings carry a location; the line length limit is an approximation.
  • simulate_event {mapId, eventId, ...} — dry-runs one event page against a state you supply (switches, variables, self switches, gold, items, answers to choices) and returns the messages shown, the changes made, the transfer it ends in and the commands it could not simulate. It covers messages, choices, conditions, loops, common events, switch/variable/self switch/gold/item changes, transfers, plugin commands, labels and jumps; battles run the branch chosen by battleResult (win, escape or lose, default win); animations and balloons (212, 213), screen fades, tint, flash and shake (221-225), waits (230), show/move/erase picture (231, 232, 235), weather (236), play/fade audio (241, 242, 245, 246, 249, 250, 251) and move routes (205) are ignored and only counted in cosmetic (the switch ON/OFF steps of a move route still apply); scripts, picture rotation and tint (233, 234) and other commands are listed as unsupported and skipped. It never touches the project.
  • editor_status — reports whether the RPG Maker editor process appears to be running (Windows only; null elsewhere) and which files this server wrote have since been modified by something else, usually the editor saving over them. It only reports.

Usage and progression analysis

These tools read the whole project (staged changeset data included) and never run the game.

  • find_usages {kind, id, limit?} lists every place one switch, variable, item, weapon, armor, skill, state, actor, class, enemy, troop, common event or map is read, written or used, as locations like Map003 event 5 page 1 command index 12 or Enemies #4 dropItems (map, event and common event ids are the real ids, pages are 1-based like the editor, and the command index is the 0-based position that lint_events also reports), with exact counts and warnings: a switch or variable that is read but never set (or set but never read), a common event nothing calls, a map nothing transfers to, an id without a name. Use it before renaming, deleting or reusing an id.
  • check_references {limit?} finds references that point at records which do not exist: a Battle Processing on troop 1 when there is no troop 1, a shop item 7, Learn Skill 12, actor 5, a transfer to a deleted map, an enemy drop or class learning that names a missing record. It checks exactly the references find_usages indexes (event commands, page conditions, enemy drops and actions, class learnings, actor class and equipment, troop members, item and skill effects, encounter lists, System startMapId and partyMembers) against the database files and MapInfos.json, groups the findings by kind and id with a count and up to three locations, and lists in notes what it did not check. Id 0 ("none") is never reported, and switches and variables are not checked. A database file that is missing or unreadable is named in notes instead of reporting everything as missing. Run it before a release and after deleting or renaming records.
  • analyze_progression {goal?, includeGraph?, limit?} follows the game from the start map and reports the reachable and unreachable maps, maps with no way out, event pages that can never run (with the first condition that is never met), switches and variables that are read but never set or set but never read, and a summary in plain language. goal ({switch}, {mapId} or {event: {mapId, eventId}}) adds a verdict with the reasons it is blocked, and includeGraph adds a Mermaid flowchart of the map transfers.

What the analysis can prove. It is an over-approximation of a playthrough: a page may run whenever its page conditions could hold, and when it runs all of its commands take effect. Switches only ever turn on and items are never lost. So unreachable and never set are proofs under that model, while reachable only means "not ruled out".

What it cannot see. Conditions inside event commands (branches, choices), damage formulas (they are evaluated JavaScript and can set switches and variables), script commands and plugin commands, transfers and battles whose target is a variable, enabled plugins and their parameters and notetags (they can call common events, set switches or move the player), and vehicles' start maps. It never models switches turning off and does not detect soft-locks. find_usages does not index every command either, and check_references sees only what the index sees (references made by script or plugin commands, notetags, plugin parameters, damage formulas and variable-designated commands are invisible to it); the list is in CHANGELOG.md. check_references decides that a record exists by its id field, not its array position (like find_usages), so a table whose rows' ids differ from their positions can give wrong answers. find_usages, check_references and analyze_progression build the project index in memory: a hostile or machine-generated project with very large Control Switches / Variables commands covering whole id ranges can use a lot of memory and time (about 1.2 GB were measured for 5000 events expanding to about 10 million references).

Confidence. uncertainty.confidence is low as soon as the project contains script or plugin commands, variable-designated transfers or battles, or enabled plugins (or a map or js/plugins.js it could not read), and the summary says why. It stays high when only conditions inside commands or damage formulas do something the analysis cannot see. Trust unreachable and dead results only when it is high; almost every project with custom plugins reports low. The same applies to the "never ..." warnings of find_usages, which carry a note when script or plugin commands could act on the id.

Balancing tools in a nutshell

Bulk edits, curve generators and import_texts are dry runs by default — they return a diff and write nothing until you pass dryRun: false. simulate_battle and balance_report use the project's real class curves, equipment, traits and damage formulas (evaluated safely: formulas are checked against a whitelist before they run). They do not model states, buffs or items, so treat them as a guide and playtest the important fights.

Backups

The first time a session modifies any file, the original is copied to <project>/.mcp-backups/<session-timestamp>/ preserving its relative path. Up to 10 sessions are kept. list_backups shows what's available; restore_backup restores one file or a whole session — and backs up the current state first, so restores are undoable.

Add .mcp-backups/ and .mcp-stamps/ to your game project's .gitignore if the game is under version control (leave .mcp-stamps/ out if you want to share stamps). Changeset journals live under .mcp-backups/changesets/ and are not pruned.

Important notes

  • Close the RPG Maker MV editor (or don't save from it) while the server edits files. The editor keeps the whole database in memory and overwrites the JSON files on save, discarding external changes. Reopen the project in the editor to see edits made here.
  • Database arrays in MV are 1-indexed with null at index 0; the tools handle this automatically, and ids always match array positions.
  • MZ projects (.rmmzproject) are accepted too — the data format is nearly identical — but they are untested.
  • Known limitations of this release (unverified editor process name, unchecked visual quality of generated maps, no scripted playtest runner, ...) are listed in CHANGELOG.md.
  • Tiles are painted with paint_tiles (not update_map, which refuses to touch data). Pick tiles via get_tileset_info / get_tileset_image; a tile's sheet must have an image assigned in the map's tileset, otherwise the tile would be invisible and the call is rejected.
  • render_map_image reads the tileset and character images from img/ (encrypted .rpgmvp deployments cannot be shown); sheets without a usable image are drawn as flat colours and listed in the answer. Water is drawn in its first animation frame.
  • export_texts writes into the project (default localization/); the file is backed up before it is overwritten and existing translations are carried over by key.
  • NW.js playtest auto-detects Steam and KADOKAWA install paths, the project's own Game.exe, and the RPGMAKER_MV_NWJS environment variable, in that order.
  • In browser playtest mode, console output stays in the browser devtools — use NW.js mode when you need playtest_log.

Building from source

For contributors or if you prefer to build locally:

sh
git clone https://github.com/Xerolo44/RPG-Maker-MV-MCP.gitcd RPG-Maker-MV-MCPnpm installnpm run build

Then use the local build with Claude Code:

sh
claude mcp add rpgmaker-mv -- node "$(pwd)/dist/index.js" --project "/path/to/YourGame"

Development

sh
npm run build   # compile TypeScript to dist/npm run test:unit  # node:test unit tests in test/ (PNG, formulas, renderer, battle maths, generators, ...)npm run smoke      # end-to-end test: real stdio client against a generated MV projectnpm test           # build + unit tests (test/) + smoke test (what CI runs)

See CONTRIBUTING.md for project layout and guidelines, CHANGELOG.md for release history, and SECURITY.md for the tool's trust model (it has full file-system access — read this before exposing --http mode beyond your own machine).

License

MIT

来源:README.md,提交 7c1bc74

工具

78

set_project

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. Discards any open changeset (its staged edits are lost).

输入参数path必填

get_project_info

Get project info

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

无需输入参数。

list_records

List database records

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

输入参数type必填

get_record

Get database record

Get the full JSON of one database record by id.

输入参数id必填type必填

update_record

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.

输入参数id必填data必填type必填merge

create_record

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.

输入参数data必填type必填

get_system

Get System.json

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

输入参数key

set_switch_name

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.

输入参数id必填name必填

set_variable_name

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.

输入参数id必填name必填

update_system

Update System.json

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

输入参数data必填

list_maps

List maps

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

无需输入参数。

get_map

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

输入参数mapId必填includeTileData

update_map

Update map properties

Shallow-merge fields into a map's JSON (e.g. displayName, note, bgm, encounterList). Refuses to touch 'data' or 'events' — use the event tools for events and paint_tiles for tiles. To switch tilesets prefer set_map_tileset.

输入参数data必填mapId必填

get_event

Get map event

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

输入参数mapId必填eventId必填

update_event

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.

输入参数event必填mapId必填eventId必填

create_event

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.

输入参数x必填y必填name必填notemapId必填pages

delete_event

Delete map event

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

输入参数mapId必填eventId必填

add_event_command

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.

输入参数indexmapId必填eventId必填commands必填pageIndex

add_dialogue

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.

输入参数lines必填mapId必填eventId必填faceNamepositionfaceIndexpageIndexbackground

create_map

Create map

Create a new map: writes MapXXX.json and registers it in MapInfos.json. The map starts empty unless `fill` is given (a ground tile for layer 0); afterwards use paint_tiles to paint it, get_tileset_info to choose tiles and add events with the event tools. Returns the new map id.

输入参数fillname必填widthheightparentIdtilesetId

event_command_reference

Event command reference

Reference table of RPG Maker MV event command codes and their parameters. Consult this before writing or editing event command lists.

无需输入参数。

get_tileset_info

Get tileset info

Describe a tileset so you can choose tiles to paint: which image is assigned to each sheet (A1-A5, B-E), the tile id ranges, and for autotile sheets every kind with its type, position on the sheet image and passability. Without `sheet` you get an overview; pass `sheet` for the detail of one sheet (for A5/B-E that includes a passability grid laid out like the image: o passable, x blocked, * drawn above characters, p partly blocked). Use get_tileset_image to see what the tiles look like. `tileIds` decodes passability and terrain flags for specific tile ids.

输入参数sheettileIdstilesetId必填

get_tileset_image

Get tileset sheet image

Return one tileset sheet (A1-A5, B-E) as an image so you can see which tile looks like what, together with its grid layout (48px tiles). Use get_tileset_info for the matching tile ids and kinds.

输入参数sheet必填tilesetId必填

set_map_tileset

Set map tileset

Switch a map to another tileset (which sheets/tile images it uses). Existing tile ids are kept as they are, so they will show the new tileset's graphics - repaint with paint_tiles if the layouts differ.

输入参数mapId必填tilesetId必填

paint_tiles

Paint map tiles

Paint tiles onto a map. Takes a list of operations applied in order: `cells` (individual positions), `rect` (filled or hollow rectangle) and `fill` (flood fill from a cell). Tiles are chosen as {sheet:'A2', kind:N} (autotile sheets A1-A4), {sheet:'B', index:N} (A5/B-E) or a raw tile id; 0 erases. Autotile edge, corner and wall shapes are calculated automatically, including re-shaping neighbours, just like painting in the editor. Layers: 0-1 ground, 2-3 upper tiles, 4 shadows, 5 regions. Typical map: fill layer 0 with a ground kind from A2, then place water/walls/objects on top. Use get_tileset_info / get_tileset_image to pick tiles and render_map to check the result.

输入参数mapId必填operations必填

render_map

Render map as text

Show a map's tiles as text so you can check what you painted. mode 'symbols' (default) draws one character per cell using the topmost tile of layers 0-3 (or only `layer`) with a legend naming each symbol; mode 'ids' prints raw tile ids of one layer. Use x/y/width/height to look at a region (default: up to 100x60 from the top-left).

输入参数xymodelayermapId必填widthheight

render_map_image

Render map as image

Render a map to a PNG image so you can SEE what it looks like: all tile layers with correct autotile shapes, shadows and tiles that draw above characters, optionally the events' character sprites, coloured event markers with their ids, region ids, a tile grid and a passability overlay (red = blocked in at least one direction). This is the visual counterpart of render_map (text) - use it after paint_tiles / create_event / connect_maps to check your work. Marker colours: blue = event with a Transfer Player command (door/exit), orange = shows text, magenta = autorun/parallel, green = anything else. Needs the tileset images in img/tilesets (sheets without an image are drawn as flat colours and listed). Large maps are shrunk to fit ~1600px; pass x/y/width/height to zoom into a region and raise tileSize for detail.

输入参数xymapId必填widthheightshowGridtileSizeshowEventsshowRegionsshowPassability

render_diff

Render map changes

Show what changed on a map compared with an earlier version: a text summary (changed tile cells, added/removed/moved/edited events) plus a PNG of the CURRENT map with changed cells outlined yellow and added or moved events outlined green. By default it compares with the most recent backup session that contains the map (the state before this session's first edit); pass against.session to pick a session folder from list_backups, or against.changeset to compare with the pre-image of a committed changeset. Use it after bulk painting or generation to review exactly what you touched. If the map has no earlier version this session, it says so.

输入参数mapId必填againsttileSize

list_plugins

List plugins

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

无需输入参数。

configure_plugin

Configure plugin

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

输入参数name必填statusparameters

add_plugin

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

输入参数name必填statusparametersdescription

remove_plugin

Unregister plugin

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

输入参数name必填

create_plugin

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.

输入参数codename必填statusdescription

read_plugin

Read plugin source

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

输入参数name必填

write_plugin

Write plugin source

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

输入参数code必填name必填

playtest_start

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.

输入参数modeportruntimePath

playtest_status

Playtest status

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

无需输入参数。

playtest_log

Playtest log

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

输入参数tail

playtest_stop

Stop playtest

Stop the running playtest process and/or HTTP server.

无需输入参数。

create_damage_skill

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.

输入参数name必填notescopempCosttpCosttpGainformula必填hitTypestypeIdcriticaloccasionvariance另有 5 个

create_healing_skill

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

输入参数name必填notescopempCosttpCostformula必填stypeIdoccasionvarianceiconIndexanimationIddescription另有 2 个

create_buff_skill

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.

输入参数name必填notebuffsscopempCosttpCostdebuffsstypeIdoccasioniconIndexanimationIddescription

create_state_skill

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

输入参数name必填notescopeactionmpCoststates必填tpCoststypeIdoccasioniconIndexanimationIddescription

search_records

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.

输入参数typelimitquery必填

search_map_events

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

输入参数limitmapIdquery必填searchCommands

list_backups

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 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. Refused while a changeset is open (commit or discard it first). The RPG Maker editor must stay closed while files are restored.

输入参数filesession

editor_status

Editor status

Check whether the RPG Maker MV editor appears to be running and which files this server wrote have since been changed by something else (usually the editor saving over them). Report only: it never blocks or undoes any edit.

无需输入参数。

validate_project

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

无需输入参数。

begin_changeset

Begin changeset

Start a transactional batch of edits. While a changeset is open, every edit tool stages its result in memory: nothing is written to disk until commit_changeset, and all reads (get_map, get_record, list_plugins, ...) reflect the staged edits. Commit writes every staged file in one step (all or nothing) and can be rolled back later with undo_changeset; discard_changeset drops the staged edits. Only one changeset can be open at a time; restore_backup is refused while one is open and set_project discards it. Playtests read from disk, so they only see committed edits. The RPG Maker editor must stay closed while the server edits the project.

输入参数label必填

commit_changeset

Commit changeset

Write every file staged by the open changeset to disk as one unit and return a per-file summary (created/modified, event/tile/record counts). Staged .json files are validated first: if any is invalid, nothing is written and the changeset stays open. Pre-images are journaled under .mcp-backups/changesets/<id>/ so undo_changeset can roll the commit back; a commit interrupted by a crash is rolled back automatically the next time the project is opened (the files found on disk are backed up first). Other edits are refused while the commit runs. If a commit fails and its files cannot all be restored, the changeset is closed and every edit is refused until undo_changeset has restored them. Until this is called, nothing of the changeset is on disk and reads reflect the staged edits. The RPG Maker editor must stay closed while the server edits the project.

无需输入参数。

discard_changeset

Discard changeset

Drop every edit staged by the open changeset. Nothing on disk changes (nothing of the changeset was on disk yet), and reads go back to the files on disk. The RPG Maker editor must stay closed while the server edits the project.

无需输入参数。

undo_changeset

Undo last changeset

Roll back the most recently committed changeset from its journal: modified files are restored byte-for-byte, files it created are deleted. Call repeatedly to step back through earlier commits. Edits made to those files after the commit are overwritten too. Refused while a changeset is open (while one is open, reads reflect its staged edits and nothing is on disk until commit). The RPG Maker editor must stay closed while the server edits the project.

无需输入参数。

connect_maps

Connect two maps

Link two maps with Transfer Player events in both directions in one call. A door event is placed on each map; stepping on (or pressing OK at) the door on map A moves the player to map B's spawn tile and vice versa. Give each side its `door` tile; add `spawn` when the player should appear next to the door instead of on it (always do this for doors drawn into walls). Both maps are validated before anything is written, and a door is refused if another event already stands on that tile (allowOverlap overrides). Use twoWay=false for a one-way link (map A's door only). Check the result with render_map_image (doors show as blue markers) and list_map_connections.

输入参数a必填b必填fadesoundtwoWaytriggerdoorNameallowOverlap

list_map_connections

List map connections

Scan every map's events for Transfer Player commands and show how the maps are linked: each door with its destination, one-way links without a way back, transfers to maps that do not exist, and maps that cannot be reached from the game's start map. Transfers whose target is chosen by variables are listed as dynamic and cannot be followed, so 'unreachable' is a hint, not proof.

输入参数mapId

bulk_update_records

Bulk update records

Change one or more fields on many database records at once, with a diff. Example - all weapons +10% attack: {type: 'weapons', changes: [{field: 'params.atk', op: 'percent', value: 10}]}. Select records with `ids` and/or `where` conditions (all must match); with neither, every record is selected. Fields are paths such as 'price', 'params.atk' (mhp/mmp/atk/def/mat/mdf/agi/luk), 'params[2]', 'damage.formula', 'traits[0].value'. Ops: set (any value), add, multiply, percent (+value%) - numeric ops round to whole numbers for integer fields (round: auto), with optional min/max clamps. DRY RUN BY DEFAULT: nothing is written until you pass dryRun=false, so show the diff to the user first. If any record fails, nothing is written.

输入参数idstype必填wheredryRunchanges必填maxPreview

generate_param_curve

Generate class parameter curve

Generate stat curves over levels and (optionally) write them into a class. Each curve goes from `start` at minLevel to `end` at maxLevel with a shape: linear, ease-in (slow start), ease-out (fast start), ease-in-out, exponential (constant growth factor) or logistic (S-curve). Without classId this is a pure preview of the numbers. With classId the class's params table is rewritten for minLevel..maxLevel (other levels are untouched) - dry run by default, pass dryRun=false to apply. Follow up with balance_report to see how the new curve plays against enemies.

输入参数curves必填dryRunclassIdmaxLevelminLevel

generate_enemy_scaling

Generate enemy scaling

Spread enemy stats along a curve for smooth difficulty progression. Give the enemies ordered from weakest to strongest; the first gets each curve's `start`, the last its `end`, the rest are interpolated with the chosen shape. Curves can target any parameter (mhp, mmp, atk, def, mat, mdf, agi, luk) plus `exp` and `gold`. Dry run by default - shows before and after per enemy; pass dryRun=false to write.

输入参数curves必填dryRunenemyIds必填

balance_report

Balance report

Measure the game's balance from its data: (1) class stat curves at chosen levels, (2) the attack skill's damage by level against a reference enemy, (3) a matrix of attackers vs enemies (average damage and hits to kill) and (4) enemy threat vs the same characters (damage of the enemy's best attack and hits to kill them). Ends with warnings: unevaluable damage formulas, curves that go down, enemies killed in one hit or immune, enemies that one-shot a character. Attackers default to the starting party. Numbers are averages with no variance, crits or misses and ignore states, items and elements beyond what the skill/traits specify - use simulate_battle for a full fight.

输入参数levelsclassIdsenemyIdsattackersreferenceEnemyId

simulate_battle

Simulate a battle

Run many simulated battles of a troop against a party and report win rate, turns, how much HP the party keeps and who does the damage or dies. Uses the project's real stats (class curves, equipment, traits), damage formulas, variance, critical hits, hit/evasion rates, agility turn order, target weighting (TGR) and enemy action ratings. Party members use `skillIds` in order (first affordable one, healing only when an ally is below 60% HP), falling back to the Attack skill. Not modelled: states, buffs, items, guarding, TP, enemy conditions on states/switches (treated as false). Seeded, so results are reproducible. Default party: the starting party at their initial level.

输入参数runsseedlevelpartytroopId必填maxTurns

export_texts

Export all game texts

Export every translatable text of the project to a CSV or JSON file inside the project (default localization/texts.csv) with columns key, context, original, translation. Covers database names/descriptions/messages, System terms and type names, the game title, map display names, and event text (dialogue boxes as one row each with lines joined by newlines, choices, scrolling text, actor name/nickname/profile commands) in maps, common events and troop battle events. If the file already exists its translations are carried over by key, so re-exporting after changes never loses work. Fill in the translation column (leave empty to keep the original), then use import_texts. See the rpgmaker-localization skill for rules about control codes and message length.

输入参数filescopeformat

import_texts

Import translated texts

Apply the translation column of a file written by export_texts back into the project's data. DRY RUN BY DEFAULT: reports what would change and nothing is written until dryRun=false. Rows with an empty translation are skipped. A row whose `original` no longer matches the project text (the text changed after export) is skipped unless force=true. Dialogue translations longer than 4 lines are split into several message boxes automatically; choices are kept in sync. Control codes (\C[n], \V[n], \N[n] ...) are compared with the original and mismatches are reported as warnings.

输入参数file必填forcedryRun

audit_assets

Audit project assets

Checks that every image and audio file the project references exists on disk, and optionally lists files nothing references. Scanned references: Actors (characterName, faceName, battlerName); Enemies battlerName (img/enemies, or img/sv_enemies when System optSideView is on); Tilesets tilesetNames; Maps (parallaxName, bgm, bgs, battleback1Name, battleback2Name, event page images); event commands 101 (face), 132/133/139/140 (battle BGM, victory ME, defeat ME, vehicle BGM), 231 (picture), 241/245/249/250 (BGM/BGS/ME/SE), 283 (battle back), 284 (parallax), 322 (actor graphics) and 323 (vehicle image) in map events, common events and troops; System (title1Name, title2Name, battleback1Name, battleback2Name, titleBgm, battleBgm, victoryMe, defeatMe, gameoverMe, boat/ship/airship bgm, sounds). Anything else is listed under notScanned, so 'unused' can include files used only by plugins or scripts. Audio is satisfied by either an .ogg or an .m4a file. caseMismatch means the file exists only with different letter case: it works on Windows but breaks on Linux, macOS and web deployments. Each list is capped at 200 entries; truncated gives the omitted counts.

输入参数includeUnused

lint_events

Lint event command lists

Statically checks event command lists in map events, common events and troop pages. Rules: unterminated-list and block-structure (missing code 0 terminator, unclosed or mismatched choices/branches/loops, indent jumps; error), unreachable-command (a command right after Exit Event Processing at the same indent; warning), long-message-line (a Show Text line too long for the window; warning), transfer-missing-map and transfer-out-of-bounds (direct Transfer Player to a map not in MapInfos or outside its size; error), missing-common-event (Common Event call to an id that does not exist; error), unnamed-switch and unnamed-variable (Control Switches/Variables on ids with no name in System.json; info). Variable-designated transfers are not checked. long-message-line removes message control codes (\C[n], \V[n], \N[n], \P[n], \I[n], \{ \} \. \| \! \> \< \^) and compares the remaining character count with maxLineChars; the default of 50 is only an approximation, since real fit depends on the font, face graphic and window width. Findings carry location {kind, mapId, eventId, page, index}; page and index are 0-based positions in the event's pages and command list (common events use page 0, troops use the troop id as eventId). minSeverity defaults to warning, so info findings appear only when requested. scope defaults to all; mapId limits the map part to one map. Maps whose file cannot be read are listed in skippedMaps. Results are sorted by severity then location and capped at 300 findings; counts cover all findings and truncated is the number cut.

输入参数mapIdscopeminSeveritymaxLineChars

simulate_event

Simulate an event

Dry-runs one map event page against a hypothetical game state and returns what it would do, without touching the project or running the game. Supported commands: Show Text (101/401), Show Choices (102/402/403/404), Conditional Branch (111/411/412: switch, variable, self switch, gold, item), Loop/Break (112/113/413), Exit Event Processing (115), Common Event (117, nested up to 8 deep), comments, Control Switches (121), Control Variables (122: constant, variable and random operands), Control Self Switch (123), Change Gold (125), Change Items (126), Transfer Player (201, ends the run) and Plugin Command (356, listed in changes as 'plugin: ...'). Battle Processing (301) is not fought: the branch picked by battleResult runs (win, escape or lose; default win) and the others are skipped; a missing branch adds 'battle: no <result> branch' to changes. A Battle Processing without branches (what the editor writes when neither Can Escape nor Continue when Loss is on) is a single command: nothing is skipped and the next command runs. Label (118) and Jump to Label (119) work: a jump goes to the first label of that name in the current command list and counts as a step, so a label loop ends 'stepLimit'; a missing label is listed in unsupported and the run continues. Presentation commands (Set Movement Route 205, animation and balloon 212/213, screen fades, tint, flash and shake 221-225, wait 230, show/move/erase picture 231/232/235, weather 236, play/fade audio 241/242/245/246/249/250/251, 505 route rows) are ignored and only counted in cosmetic, not listed in unsupported; the one exception is the switch ON/OFF steps of a Set Movement Route, which do change the simulated switches (changes: 'switch N → ON (move route)'; only the first 1000 route entries are scanned, each costing one step, and a longer route adds an unsupported note). A battleResult of escape or lose on a battle that cannot be escaped or lost still runs the branch but adds a note to changes. Everything else (script 3

输入参数goldpageseeditemsmapId必填choiceseventId必填switchesvariablesbattleResultselfSwitchesunknownCondition

find_usages

Find usages

Lists everywhere one switch, variable, item, weapon, armor, skill, state, actor, class, enemy, troop, common event or map is read, written or used, and warns about dead ends. Use it before renaming, deleting or reusing an id. reads: page conditions, Conditional Branch (111), variable operands and \V[n] text escapes; writes: Control Switches/Variables (121/122), Change Items/Weapons/Armors (126-128), Change Party Member (129), Change State/Skill (313/318), set-switch route steps; uses: Transfer Player (201), Common Event (117), Battle Processing (301), shops (302/605), actor commands, enemy drops and actions, class learnings, actor equipment, troop members, item/skill effects, map encounter lists, System startMapId and partyMembers. It reads staged changeset data. Each location is a string: 'Map003 event 5 page 1 command index 12', 'CommonEvent 4 command index 7', 'Troop 2 page 1 command index 3', 'Enemies #4 dropItems', 'System startMapId', 'Map003 encounterList'. Map ids, event ids, common event ids and troop ids are the real ids and pages are 1-based like the editor shows them, but 'command index N' is the 0-based position in the command list (the index lint_events reports). A location without a command index is a page condition. counts are the true totals; each list is cut at limit entries and truncated gives the omitted counts. warnings cover: a switch or variable that is read but never set, or set but never read; a common event never called (autorun and parallel common events are exempt); a map nothing transfers to; and an id with no name or record (unknown id, not an error). Script commands (355), plugin commands (356), variable-designated transfers and battles, notetags and plugin parameters are not understood, so every 'never ...' warning carries a note when the project has script or plugin commands (or truncated range commands) that could act on the id. Only the 121/122 ids up to 1000 per command are indexed.

输入参数id必填kind必填limit

check_references

Check references

Finds references that point at records which do not exist: a Battle Processing (301) on a missing troop, a shop item (302/605), Change Items/Weapons/Armors (126-128), Learn/Forget Skill (318), Change State (313), Change Party Member (129) and the other actor commands, Common Event calls (117), Transfer Player (201) or Set Vehicle Location (202) to a missing map, page conditions on a missing item or actor, enemy drops and actions, class learnings, actor class and equipment, troop members, item and skill effects, map encounter lists and System startMapId and partyMembers. It uses the same index as find_usages, so it checks exactly the references find_usages lists (staged changeset data included). A record exists when its database file (Items, Weapons, Armors, Skills, States, Actors, Classes, Enemies, Troops, CommonEvents) holds a non-null row whose id field is that id (not its array position, as in find_usages), or MapInfos.json lists the map. Id 0 means 'none' (an empty equipment slot, no drop) and is never reported. Switches and variables are not checked (plain numbers; lint_events reports unnamed ones). Run it before a release and after deleting or renaming records, and use find_usages on one reported id to see every place. Returns {summary, missing: [{kind, id, count, locations, severity: 'error'}], truncated, counts: {distinctMissing, references}, notes}. missing is grouped by kind and id, ordered by kind (item, weapon, armor, skill, state, actor, class, enemy, troop, commonEvent, map) then id; count is the number of references and locations lists at most 3 of them (same format as find_usages). missing is cut at limit groups and truncated is the number cut. A database file that is missing or unreadable is named in notes and its references are NOT reported as missing. notes also state what is not checked: references made by script commands, plugin commands, notetags, plugin parameters, damage formulas, trait codes and variable-designated transfers and battles (wit

输入参数limit

analyze_progression

Analyze progression

Answers 'can the player get from the start map to X, and what can never happen?' for the whole project, without running the game. Model (an over-approximation): starting at System startMapId, a page may run whenever its page conditions could hold, and when it runs ALL of its commands take effect. Switches only ever turn ON, items are never lost, and conditions inside event commands (branches, choices) are ignored. So 'unreachable' (maps, pages, goals) is a proof under the model, while 'reachable' only means 'not ruled out'. It cannot see script commands (355), plugin commands (356), variable-designated transfers or battles, enabled plugins (parameters, notetags) or anything else a plugin does. Each of those, an unreadable map or an unreadable js/plugins.js lowers uncertainty.confidence to 'low'; only trust 'unreachable' and 'dead' results when confidence is 'high'. Returns reachableMaps, unreachableMaps, deadEndMaps (no exit), deadPages (pages that can never run, with the first unmet condition), switches/variables read-but-never-set and set-but-never-read, edges (direct transfers), notes, a plain-language summary and names (map id to name). goal (exactly one of switch, mapId or event) adds a verdict with up to 10 blockedBy reasons. includeGraph adds a Mermaid flowchart of the map transfers. Lists are cut at limit (the summary counts stay exact); truncated is also set when an analysis cap was hit (see notes). Staged changeset data is analysed.

输入参数goallimitincludeGraph

build_dialogue_tree

Build dialogue tree

Compiles a nested tree of nodes into correctly indented event commands and optionally inserts it into an event page, so you never hand-write indents, block terminators or move-route rows. Covers dialogue, branching, switches and variables, cutscenes (screen effects, audio, pictures, animations, move routes) and game flow (battles, shops, items, gold, party, scenes, labels). With mapId + eventId the commands are inserted at indent 0 before the page's end (or at `index`), like add_event_command; without them, or with dryRun, nothing is written and the compiled commands are returned in `preview`. `tree` is an array of nodes; every node is an object with one main key, and unknown keys are rejected. choices, if and battle bodies nest at most 8 levels deep (each body counts as a level). A node that is invalid anywhere in the tree fails the whole call and nothing is written. Node vocabulary, in three groups. (1) MESSAGES AND FLOW: {say: string | string[], face?: {name, index}, background?: 0|1|2, position?: 0|1|2} (4 lines per message box; "\n" splits lines; control codes like \C[2] are kept as written); {choices: [{label, then?: Node[]}] (1-6), cancel?: "disallow" (default) | "branch" | choiceIndex}; {if: Condition, then?: Node[], else?: Node[]} with Condition = {switch, is?} | {variable, op: "eq"|"ne"|"gt"|"gte"|"lt"|"lte", value} | {selfSwitch: "A".."D", is?} | {gold} (party has at least) | {item} (party has item); {setSwitch: {id, value}} | {setVariable: {id, op: "set"|"add"|"sub", value}} | {setSelfSwitch: {ch, value}} | {transfer: {mapId, x, y, direction?: 0|2|4|6|8, fade?: 0|1|2}} | {raw: [{code, indent?, parameters?}]} (indent is relative to the node's position). Example: [{"say":"Will you help?","face":{"name":"Actor1","index":0}},{"choices":[{"label":"Yes","then":[{"setSwitch":{"id":5,"value":true}},{"say":"Thank you!"}]},{"label":"No","then":[{"say":"A pity."}]}],"cancel":"branch"}]. (2) CUTSCENE, where target is "player" | "this" (the running event) | a positiv

输入参数tree必填indexmapIddryRuneventIdpageIndex

create_event_from_template

Create event from template

Creates a complete, ready-to-use map event at (x, y) from a template, in one write. Refuses out-of-bounds tiles, and refuses a tile that already holds an event unless allowStack is true. Graphics default to none: events are INVISIBLE in game until an image is supplied (chest: closedImage/openImage, npc: image; locked_door, inn, shop and save_point never get a graphic and are meant to sit on a tile that already looks right). Templates and their params: chest {reward: {gold?, item?: {type: item|weapon|armor, id, count?}}, message?, closedImage?, openImage?} (two pages: the action button opens it and sets self switch A, then an empty opened page; if only closedImage is given, openImage defaults to the same graphic with direction 8 - the opened-chest frame of the standard chest sheets); locked_door {keyItemId, destination: {mapId, x, y, direction?: 0|2|4|6|8}, lockedMessage?, consumeKey?} (transfers the player if the party holds the key); inn {price, greeting?} (Stay/Leave choice; staying charges gold, fades out, restores the party, fades in); shop {goods: [{type: item|weapon|armor, id, price?}] (1-40; price defaults to the database price), purchaseOnly?}; save_point {} (opens the save screen); npc {lines: string[], face?: {name, index}, image?}. Image = {characterName, characterIndex (0-7), direction?: 2|4|6|8, pattern?: 0|1|2}. Returns { eventId, name, pages }.

输入参数x必填y必填facenamegoodsimagelinesmapId必填pricerewardmessagegreeting另有 9 个

generate_map

Generate map

Procedurally generate a dungeon (rooms joined by corridors) or a cave (organic, one connected region) and paint it with a tile profile. Give exactly one of `mapId` (generate into an existing map, using its size and tileset) or `create` (make a new map and register it in MapInfos.json). An existing map that has any tile or any event is refused unless `overwrite` is true; overwrite resets every tile layer and removes all events. `seed` makes the result repeatable; when omitted a random seed is picked, and the seed used is always returned. The profile (floor, wall, optional wallTop, optional weighted decor) defaults to suggestTileProfile, which works from the tileset's data only: the lowest-numbered walkable A2 kind as floor (else the first walkable A5 tile), the lowest-numbered blocking A4 wall kind as wall with the floor-rule A4 kind above it as wall top (else the first blocking A5 or B tile), and no decor. The profile used and the reasoning are returned as profileUsed and profileNotes. Nothing is written when the profile's floor is not walkable, its wall or wall top does not block movement, a sheet has no image, or the painted map is not fully reachable from the entrance. Markers are empty placeholder events at priority 0 (below characters, so they never block the player) named Entrance, Exit and Chest 1..n, placed on floor cells; chests are random floor cells away from the entrance and exit, chosen so that no chest cuts off any part of the map. `markers` defaults to {entrance: true, exit: true, chests: 0}. The result lists each marker's eventId and position under `markers`. Afterwards: call render_map_image to look at the result (consider showPassability); wire doors to other maps with connect_maps using the returned entrance and exit coordinates; fill the chest markers with create_event_from_template or the event tools. A marker occupies its tile: delete it with delete_event before placing a door or chest there, or pass allowOverlap (connect_maps) / allowStack (cr

输入参数kind必填seedmapIdcreatemarkersprofileoverwrite

capture_stamp

Capture stamp

Save a rectangle of a map as a reusable stamp in <project>/.mcp-stamps/<name>.json: all six layers (tiles, shadow bits, regions) and, with includeEvents (default true), the events standing inside it. Use place_stamp to paste it onto any map of the same tileset. Width and height are 1-64 and the whole rectangle must lie inside the map. Names are 1-64 characters (letters, digits, space, _ and -, starting with a letter or digit). An existing stamp is only replaced when overwrite is true. Stamps are written like any project file, so inside an open changeset they are only staged until commit_changeset. Add .mcp-stamps/ to .gitignore next to .mcp-backups/ unless you want to share stamps.

输入参数x必填y必填name必填mapId必填width必填height必填overwriteincludeEvents

place_stamp

Place stamp

Paste a stamp made with capture_stamp onto a map with its top-left corner at (x, y). The whole stamp must fit inside the map (it is never clipped) and the map must use the same tileset the stamp was captured from. The rectangle is REPLACED on every layer: empty stamp cells erase what was there. Autotile cells (A1-A4) are re-shaped so their edges blend with the surroundings, including the cells next to the stamp; all other tiles, shadow bits and regions are copied as they are. With includeEvents (default true) the stamp's events are added with new ids and moved to the placement; if one would land on a cell that already has an event, nothing is placed and the cells are listed (includeEvents: false places only the tiles). There is no rotate or mirror. A backup of the map is kept.

输入参数x必填y必填name必填mapId必填includeEvents

list_stamps

List stamps

List the stamps saved in <project>/.mcp-stamps/ (name, size, tilesetId, event count), sorted by name. Stamps captured inside a changeset that is still open are not listed until it is committed.

无需输入参数。

import_asset

Import asset

Copy an image or sound file from this computer into the project: <project>/<folder>/<name>.<ext>. source must be an absolute local path to a regular file (no relative paths, network/UNC shares, devices or symbolic links). The type is read from the file's header, never its extension: img/* folders take files with a PNG header (max 32 MiB; only the signature + IHDR is checked, not the whole image), audio/* folders take files whose header is Ogg (OggS) or ISO-BMFF/M4A (ftyp) (max 128 MiB; only the header is checked, not the codec or the full file); the extension (.png, .ogg, .m4a) is chosen from the detected header. name defaults to the source file name without its extension and must be 1-64 characters from A-Z a-z 0-9 space _ ! $ ( ) - (no dots, no path); a '$' prefix on a character sheet means one character per sheet, '!' means no offset. An existing file with the same name (letter case ignored) is only replaced with overwrite: true; the session backup (list_backups / restore_backup) keeps the file as it was before this server session first touched it (until set_project is called again, which starts the snapshots over), so a file that was itself created or changed earlier in the same session has no backup of that intermediate version. Nothing is converted or resized; warnings flag sheet sizes that do not fit the folder's layout, and for audio a missing sibling format (MV's web build needs both .ogg and .m4a). Refused while a changeset is open (binary files cannot be staged): commit or discard it first.

输入参数namefolder必填source必填overwrite

list_assets

List assets

List the image and sound files in the project's asset folders (img/* and audio/*, 18 folders; all of them or one `folder`). Each file shows its name (without extension), ext, size in bytes and, for images, the pixel size read from the PNG header, plus warnings (a header that does not match the extension, or a sheet size that does not fit the folder). Only the first 64 bytes of each file are read, so a sound's type is judged from its header alone, not the codec or the whole file. Sub-directories and files with other extensions (.rpgmvp, .txt, ...) are skipped. With includeUsage (default true), files in the folders the reference scan covers (all except img/system and img/animations) get usedBy (at most 3 places, e.g. 'Actor 1', 'Map003 event 5') and unused (true when nothing in the database, maps, common events or troops references the name). Names are matched case-sensitively, so a reference that differs only in letter case shows the file as unused: run audit_assets to find case mismatches and missing files. A plugin or script that loads a file by name is not seen, so check before deleting. Files with names outside the import rule (dots, non-ASCII) are listed too, but preview_asset cannot open them. Interlaced PNGs are flagged in warnings. A folder that cannot be read gets an `error` on its entry instead of failing the listing. Files are sorted by name; each folder shows at most `limit` files and `truncated` counts the rest.

输入参数limitfolderincludeUsage

preview_asset

Preview asset

Show a PNG from an img/* folder as an image so you can see it, with its pixel size, file size and, for img/characters and img/faces, the sheet layout implied by the name and size. name is the file name without .png and must match an existing file exactly (see list_assets). The image is scaled down (nearest neighbour, aspect kept) to at most maxSize pixels on its longer edge; smaller images are shown as they are. Files over 32 MiB or 16 million pixels, interlaced PNGs and files that are not valid PNGs are refused. Only names that pass the asset name rule (1-64 characters from A-Z a-z 0-9 space _ ! $ ( ) -) can be opened, even though list_assets may show files with other names. Audio cannot be previewed.

输入参数name必填folder必填maxSize

install_skills

Install skill files

Copy the bundled RPG Maker skill files (workflow guides for map building, event writing, balancing, localization, plugins) into the project's .claude/skills folder so Claude Code picks them up automatically in that project. The same files are always available as resources (rpgmaker://skills/<name>). Existing skill folders are skipped unless overwrite=true.

输入参数scopeskillsoverwrite

版本历史

4
  1. v0.5.1最新Oct 25, 2026
  2. v0.4.0Oct 25, 2026
  3. v0.2.0Oct 24, 2026
  4. v0.1.0Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分