Rpgmaker Mv MCP

RPG Maker MV MCP Server

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:

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

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

Configure Claude Desktop

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.

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:

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

This starts a Streamable HTTP MCP endpoint at https://127.0.0.1: /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)

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:

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