RpgMakerMVUltimate MCP

What DiegoLopez0208/RpgMakerMVUltimate-MCP MCP server does

DiegoLopez0208/RpgMakerMVUltimate-MCP MCP server connects an AI agent to a real RPG Maker MV project stored on disk. Its tools cover project inspection, map generation, map and event editing, database changes, system and plugin-related operations, validation, and playtesting. The server is intended to work with the project’s actual files and IDs rather than asking an agent to fabricate references.

Map generation supports procedural, semantic, blank, themed, template, batch, and duplicate modes. Procedural generation can use bundled RTP templates or terrain and dungeon algorithms for themes without a matching template. Projects can also be mined to derive semantic layouts and tileset information without modifying the source project.

How it works

The server communicates with an MCP client over a local process and reads the folder identified by RPGMAKER_PROJECT_PATH. That folder should contain RPG Maker MV’s data/, js/, and index.html files. If the environment variable is not supplied, the server can start and receive a project path later through set_project_path.

Agents can begin with get_project_context to inspect available content and real IDs, then use analyze_project for an overview containing health information, counts, and unreachable maps. Changes are written to project files.

An optional live bridge connects the server to a game launched for playtesting. After the bridge plugin is installed and started, the agent can receive exceptions, console messages, scene changes, player position, event execution details, FPS, heap information, and screenshots. It can also reload a changed map without losing party state. The bridge listens on ws://127.0.0.1:32123.

Setup and configuration

Use the published npm executable with an MCP client configuration:

{
  "mcpServers": {
    "rpgmaker-mv": {
      "command": "npx",
      "args": ["-y", "rpgmaker-mv-mcp"],
      "env": {
        "RPGMAKER_PROJECT_PATH": "C:/path/to/project"
      }
    }
  }
}

Node.js 18 or newer is listed as a requirement. The project can also be built from source with npm install, npm run build, and npm start, while providing the project path through the environment. Restart the MCP client after adding or upgrading the server because clients load tool definitions at startup.

Tools and capabilities

DiegoLopez0208/RpgMakerMVUltimate-MCP MCP server exposes 13 consolidated tools. The documented operations include:

• Inspecting project context and analyzing project health.
• Generating maps from RTP templates, semantic layouts, or other supported modes.
• Managing map events and editing project data.
• Mining existing maps into cached semantic templates under .mcp-cache/.
• Starting the live bridge, collecting telemetry, and issuing bridge commands.
• Reloading maps or individual database files during a playtest.
• Capturing screenshots to .mcp-cache/screenshots/ for later inspection.

The bridge plugin is restricted to NW.js test runs launched with a test argument. System.json and Tilesets.json cannot be hot-reloaded; those changes require a fresh playtest.

Limitations and notes

The server works with RPG Maker MV projects, not a general-purpose game engine. Procedural templates use tile IDs associated with RTP sheets, so changing tilesets can make those maps appear incorrectly. Semantic generation is the documented option for custom or non-RTP tilesets, but it requires a suitable tileset profile or mined project data.

The live bridge is optional and requires installing its plugin into the project, starting the bridge, and running the game in the supported test configuration. Without the bridge, playtest opens the game but does not provide the same telemetry or feedback loop. The material does not document remote hosting, external API credentials, or a license name.