RPG Maker MV Copilot MCP Server

An AI copilot for existing RPG Maker MV projects. Debug events, edit maps and database entries, and verify changes with repeatable playtests.

What it does

• Debug events: inspect switch conditions, trace references, and investigate why an event never fires.
• Validate projects: detect broken transfers, missing references and assets, and unreachable maps.
• Build content: generate maps and create NPCs, chests, shops, doors and battles through event presets.
• Edit the database: manage actors, classes, skills, items, enemies, troops and other MV entries.
• Search project text: find names, dialogue, descriptions and notes with offline Unicode text matching.
• Playtest: run scripted checks in the real MV engine. The optional live bridge adds telemetry, screenshots, video recording and hot reload.

The server exposes 18 consolidated MCP tools. Search and analysis report unreadable files so incomplete results are visible.

Installation

Requires Node.js 20.19.0 or newer and an MCP-compatible client.

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

Replace the example path with your project folder containing data/ and js/. Restart your MCP client after configuring the server.

## Check your setup

npx -y rpgmaker-mv-mcp --doctor "/absolute/path/to/project"

The read-only check reports project validity, Playwright and Chromium availability, bridge plugin presence, and vision configuration.

## Start with a useful task

Ask your assistant:

> Inspect my project without changing it. Report unreadable files, find the condition blocking the door I name, and explain where its switch is set.

Then preview the intended edit and verify it with a playtest.

## Requirements and limits

- Use a copy of your project and close the MV editor before editing files.
- Headless playtests require Chromium and the project's engine and assets.
- The live bridge requires its plugin and an NW.js playtest.
- AI image analysis is optional and requires a configured vision endpoint.
- Text search is lexical; it does not expand synonyms or translate queries.
- RTP templates require compatible tilesets. Generated layouts still need event wiring and validation.
- Third-party plugin compatibility and visual quality require project-specific checks.

## Links

- First-result guide
- Repository and full documentation
- npm package
- Report an issue

Transport: stdio · License: MIT