Codync
A free, open-source 1:1 alternative to Grok Bot and Muse. Message Claude Code, Codex, Cursor and 40+ coding agents as persistent bots from your iPhone, Mac or Linux desktop. Group chats, threads, appr
A Small MCP Server for helping in creation of RPG Maker MV Games
Translation pending
Developer toolsTypeScript · JavaScriptGitHub @Xerolo44Self-installOwner unconfirmed
Paste into Claude or ChatGPT for installation instructions suited to your environment.
Have you tried it? One tap is enough. No sign-in needed.
Owners of public repositories under a personal GitHub account can sign in to verify ownership and manage the introduction themselves. No administrator approval is needed.
Sign in, generate a verification file, and commit it to this repository’s default branch within 30 minutes. Files on other branches or forks do not count. Then check the file below to manage the project without administrator approval. Keep the file to retain your access.
If needed, you will go to sign-in. After signing in, return here and press your chosen verification button again.
Installable projects can be verified without a deployment domain. Use GitHub sign-in for a personal repository, or the repository verification file above for an organization repository.
Ask about other verification options
The maker's introduction consists of the line above. Read the repository README for more details. Repository README ↗
Loading the full README.
Read the full README ↗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?"
render_map shows the result as text.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.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_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).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.md workflow guides, reference
tables as MCP resources and ready-made prompts (new_town, balance_check, ...), see
Skills, prompts and resources.js/plugins.js format.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.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.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.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..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.Requires Node.js 18+.
The easiest way for Claude Code or Claude Desktop users:
npm install -g @xerolo44/rpgmaker-mv-mcp
Then configure it (see below). The package is available on npmjs.com and in the MCP Registry.
claude mcp add rpgmaker-mv -- npx @xerolo44/rpgmaker-mv-mcp --project "/path/to/YourGame"
Add to claude_desktop_config.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.
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:
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.
| Group | Tools |
|---|---|
| Project | set_project, get_project_info |
| Database | list_records, get_record, update_record, create_record, get_system, update_system, set_switch_name, set_variable_name |
| Skill helpers | create_damage_skill, create_healing_skill, create_buff_skill, create_state_skill |
| Search | search_records, search_map_events |
| Maps & events | list_maps, get_map, create_map, update_map, get_event, update_event, create_event, delete_event, add_event_command, add_dialogue, event_command_reference |
| Authoring | build_dialogue_tree, create_event_from_template |
| Tilesets & painting | get_tileset_info, get_tileset_image, set_map_tileset, paint_tiles, render_map, render_map_image, render_diff |
| Generation | generate_map, capture_stamp, place_stamp, list_stamps |
| Map connections | connect_maps, list_map_connections |
| Bulk & balancing | bulk_update_records, generate_param_curve, generate_enemy_scaling, balance_report, simulate_battle |
| Localization | export_texts, import_texts |
| Skill files | install_skills |
| Plugins | list_plugins, configure_plugin, add_plugin, remove_plugin, create_plugin, , |
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.
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:
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_infodatabase (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_skillmaps (11): list_maps, get_map, update_map, get_event, update_event, create_event, delete_event, add_event_command, add_dialogue, create_map, event_command_referencetiles (5): get_tileset_info, get_tileset_image, set_map_tileset, paint_tiles, render_maprender (2): render_map_image, render_diffplugins (7): list_plugins, configure_plugin, add_plugin, remove_plugin, create_plugin, read_plugin, write_pluginplaytest (4): playtest_start, playtest_status, playtest_log, playtest_stopsearch (2): search_records, search_map_eventsmaintenance (8): list_backups, restore_backup, editor_status, validate_project, begin_changeset, commit_changeset, discard_changeset, undo_changesetconnect (2): connect_maps, list_map_connectionsbalance (5): bulk_update_records, generate_param_curve, generate_enemy_scaling, balance_report, simulate_battlelocalization (2): export_texts, import_textsFor a multi-step change, wrap it in a changeset instead of letting every call hit the disk:
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.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.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.
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/):
| Skill | Covers |
|---|---|
rpgmaker-mv-workflow | Safety rules, data conventions, which tool to use for what, assets and analysis before release |
rpgmaker-map-building | Plan → paint → look → fix loop, layers, tile choice, connecting maps |
rpgmaker-event-writing | Dialogue, choices, indentation rules, switches, one-time chests, triggers |
rpgmaker-balancing | Targets, report/simulation workflow, curves, bulk edits with dry runs |
rpgmaker-localization | Export/import workflow, control codes, message length |
rpgmaker-plugin-dev | Plugin 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.
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.
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 (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.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.
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).
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.
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.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):
[
{ "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.
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.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.
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.
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.
null at index 0; the tools handle this
automatically, and ids always match array positions..rmmzproject) are accepted too — the data format is nearly identical —
but they are untested.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.Game.exe, and the RPGMAKER_MV_NWJS environment variable, in that order.playtest_log.For contributors or if you prefer to build locally:
git clone https://github.com/Xerolo44/RPG-Maker-MV-MCP.git
cd RPG-Maker-MV-MCP
npm install
npm run build
Then use the local build with Claude Code:
claude mcp add rpgmaker-mv -- node "$(pwd)/dist/index.js" --project "/path/to/YourGame"
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 project
npm 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).
read_pluginwrite_plugin| Playtest | playtest_start, playtest_status, playtest_log, playtest_stop |
| Analysis | audit_assets, lint_events, simulate_event, find_usages, check_references, analyze_progression |
| Assets | import_asset, list_assets, preview_asset |
| Safety | list_backups, restore_backup, validate_project, editor_status, begin_changeset, commit_changeset, discard_changeset, undo_changeset |
authoring (2): build_dialogue_tree, create_event_from_templategeneration (4): generate_map, capture_stamp, place_stamp, list_stampsanalysis (6): audit_assets, lint_events, simulate_event, find_usages, check_references, analyze_progressionassets (3): import_asset, list_assets, preview_asset