RPG Maker MV Ultimate MCP Server

A Model Context Protocol server that lets an AI agent edit a real RPG Maker MV project on disk — database, maps, events, system — through 13 consolidated tools, validated against the actual engine so the output is coherent and playable — and it can reason about the project (validate references, explain why an event never fires, critique a map) via analyze_project.

Its headline feature is knowledge-driven map generation: instead of painting tiles procedurally, generate_map clones hand-authored reference maps from 106 bundled RTP templates (real multi-tile buildings, walls, furniture) and adapts them to your project's tilesets — falling back to procedural generation only for themes without a template.

The 101 fine-grained v4 tool names still work as call aliases (set RPGMV_LEGACY_TOOLS=1 to also advertise them).

Install

The package ships an executable, so no clone is required. Add it to your MCP client:

hljs language-json

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

Works with Claude Desktop, Claude Code, opencode, and any MCP-compatible client. The server starts even without RPGMAKER_PROJECT_PATH — call set_project_path at runtime if you didn't set it.

From source

hljs language-bash

git clone https://github.com/DiegoLopez0208/RpgMakerMVUltimate-MCP
cd RpgMakerMVUltimate-MCP
npm install
npm run build
RPGMAKER_PROJECT_PATH=/path/to/your/project npm start

The 13 tools

Tool	Purpose
`query_database`	List / get by ID / search any database (actors, classes, skills, items, weapons, armors, enemies, states, troops, tilesets, common events, animations)
`create_database_entry`	Create entries, with presets: `damage_skill`, `healing_skill`, `buff_skill`, `state_skill`, `boss_enemy`, `encounter_troop`
`update_database_entry`	Partial updates (incl. troops & animations); append commands to common events; add enemies to troops
`delete_database_entry`	Delete entries incl. troops & animations (with reference-breakage warnings)
`query_map`	Map tree, full map data, events, single event, lint (`validate`), offline ASCII render
`generate_map`	Knowledge-driven generation: clones a real reference map per theme (or pure procedural / blank / themed / a specific template / batch / duplicate)
`edit_map`	Fill tile layers, set display names, organize the map tree, connect two maps, set encounters
`manage_map_event`	Create (presets: npc, chest, teleport, door, shop, inn, boss, puzzle_switch), update, convert an existing event into a merchant/inn/sign, delete, add commands, bulk-populate
`manage_system`	Game title, switch/variable names, starting position; author a plugin (`create_plugin`), scaffold a new project (`scaffold_project`), and run the game (`playtest`) / open it in the editor (`open_editor`)
`analyze_project`	Read-only project intelligence — `overview`, `index`, `validate`, `graph`, `usage`, `explain`, `ast`, `plugins`, `critique`, `refactor`, `search` (see below)
`get_project_context`	Project digest, asset index, per-tileset tile IDs, bundled-template catalog
`set_project_path`	Switch projects at runtime
`analyze_image`	Optional Vision-AI image analysis, plus offline tileset grid measurement and quadrant colors

Scaffold, run & write safety

Write safety. Every project write is atomic (temp file + rename, so an interrupted call can't leave half-written JSON) and keeps rotated timestamped backups under .mcp-backups/ (last N, RPGMV_BACKUP_KEEP, default 10). Pass dryRun: true to any mutating tool to preview the change without touching disk.
Scaffold a new project. manage_system { action: "scaffold_project", destPath, title? } clones the engine's blank template (NewData) into a new directory — the same thing the editor's New Project does — refusing to overwrite an existing project.
Run it. manage_system { action: "playtest" } launches the active project through the engine's bundled nwjs runtime (like the editor's Playtest button), so an agent can actually see a change running; open_editor opens it in RPGMV.exe. The install is found via install / the RPGMAKER_MV_INSTALL env var / the default Steam path (Windows).
Author plugins. manage_system { action: "create_plugin", name, ... } writes js/plugins/<name>.js with a correct @plugindesc/@param/@help header and registers it in js/plugins.js.

Map generation (knowledge-driven)

generate_map defaults to mode: "procedural", which is smarter than the name suggests:

For themes with a matching RTP reference template — town, village, dungeon, interior, castle, world, and more — it clones a hand-authored map from the 106 bundled templates, picking the closest size, so you get real 3D-looking buildings, walls and furniture instead of flat tile noise.
For themes without a template (beach, swamp, desert, …) it generates procedurally (Perlin terrain, BSP dungeons, cellular caves).
Same seed + params → the same map. Pass templateId to force a specific template, or useTemplate: false to force pure procedural.

Other modes: "blank" (empty canvas you paint with edit_map), "themed" (simple tile layout), "template" (instantiate one specific bundled map by templateId), "batch" (many maps at once), "duplicate" (copy an existing map).

hljs language-json

{
  "tool": "generate_map",
  "arguments": { "mode": "procedural", "theme": "town", "name": "Riverbend", "width": 40, "height": 30 }
}

Combat themes (dungeon/cave/world/fortress/sewer/volcano) auto-wire random encounters from your existing troops, and town/village auto-create enterable house interiors with two-way warps. List available templates with get_project_context { detail: "templates" }.

Themes: forest town village castle dungeon cave beach desert swamp ruins interior snow harbor volcano sewer fortress magic_forest magic_interior space_interior space_exterior world

Offline map inspection

No API needed:

query_map { view: "ascii", mapId } — render a map as a character grid with event markers (the cheapest way to "see" a layout and pick coordinates).
query_map { view: "validate", mapId } — lint for invalid tile IDs, broken transfers, and missing event terminators.

Project intelligence (`analyze_project`)

Read-only — it understands the whole project instead of re-reading files, so an agent can reason about a game it didn't build. All offline.

{ view: "overview" } — call this first on an unfamiliar project: counts, a health summary, and maps unreachable from the start.
{ view: "validate" } — every consistency problem at once: broken transfers, missing map files, dangling common-event/item/troop references, duplicate IDs, unused switches/variables, unreachable maps.
{ view: "explain", target: "switch", id } — why something never happens, e.g. "Switch 12 is read/gated in 3 places but is never set ON" (the usual cause of a door that never opens). target: "map" reports what a deletion would strand.
{ view: "usage", kind: "variable", id } — every event/common-event/troop that touches it (with read/write roles).
{ view: "graph" } — the map transfer network and reachability.
{ view: "ast", mapId, eventId } — an event's logic as a readable tree.
{ view: "plugins" } — what plugins the project uses, their parameters and commands.
{ view: "critique", mapId } — a designer-style review of one map (dead space, empty/cluttered, event spread, monotony) with justified suggestions.
{ view: "refactor" } — duplicated event logic worth extracting into a Common Event.
{ view: "search", query: "the blacksmith" } — find things by meaning across names, dialogue and descriptions.

Vision AI (optional)

analyze_image { mode: "ai" } sends a project image (tileset, sprite, screenshot, battler) to any OpenAI-compatible vision endpoint. It is disabled by default — nothing is sent anywhere unless you configure it. The other modes ("grid", "colors") and all other tools work fully offline.

Variable	Required	Description
`VISION_API_URL`	to enable	Base URL of the vision API (e.g. `https://api.openai.com`, `http://localhost:11434`). Unset = vision disabled.
`VISION_API_KEY`	optional	Bearer token; only sent when set.
`VISION_MODEL`	optional	Model name (default `meta/llama-3.2-90b-vision-instruct`).
`VISION_API_PATH`	optional	Endpoint path (default `/v1/chat/completions`).

hljs language-bash

# OpenAI
VISION_API_URL=https://api.openai.com VISION_API_KEY=sk-... VISION_MODEL=gpt-4o npm start
# Ollama (local, no key)
VISION_API_URL=http://localhost:11434 VISION_MODEL=llava npm start

Supported backends: OpenAI, Ollama, LocalAI, NVIDIA NIM, vLLM, LiteLLM, or any OpenAI-compatible proxy.

Agent Skill (recommended for any AI agent)

A portable Agent Skill teaches any model (Claude, DeepSeek, …) the correct, crash-free workflow — building maps with generate_map and adding content with manage_map_event presets instead of hand-painting tiles or guessing IDs. It lives at skill/rpgmaker-mv-mcp/SKILL.md.

hljs language-bash

# Claude Code / Claude.ai
npx degit DiegoLopez0208/RpgMakerMVUltimate-MCP/skill/rpgmaker-mv-mcp ~/.claude/skills/rpgmaker-mv-mcp
# opencode
npx degit DiegoLopez0208/RpgMakerMVUltimate-MCP/skill/rpgmaker-mv-mcp ~/.opencode/skills/rpgmaker-mv-mcp

The skill is also listed in awesome-claude-skills.

Knowledge base

Static JSON reference data in knowledge/, extracted from the RPG Maker MV corescript and the bundled maps:

File	Content
`tile-ids.json`	Tile ID ranges, autotile formula, sheet descriptions
`passage-flags.json`	Flag bits, common flags, passage check logic
`event-commands.json`	~140 event command codes with parameter schemas
`enums.json`	Scope, occasion, hitType, damageType, restriction, etc.
`trait-effect-codes.json`	Trait codes 11-64, effect codes 11-45
`database-schemas.json`	Full schemas for all MV data types
`image-paths.json`	img/ directories, tileset slots, naming conventions
`map-templates.json`	Index of the 106 bundled reference maps
`stamps.json`	Mined multi-tile object stamps (trees, props) per tileset
`maps/`	106 RTP reference map JSONs used for template cloning

Feedback & contributing

This server is actively developed and feedback is very welcome — bug reports, weird maps, missing tools, or ideas. Please open a GitHub Issue with what you asked the agent to do and what you got (an exported map JSON or a screenshot helps a lot).

Known limitations & roadmap

Decoration/object semantics are best-effort; rare multi-tile objects may be placed as single tiles.
Town and dungeon layouts keep improving — planned: central plaza/well landmark, houses in rows facing roads, fences/yards, richer road networks, more dungeon-room variety.
Vision AI is optional and requires your own endpoint.

Development

hljs language-bash

npm install
npm run build      # tsc compile (+ copies knowledge/ into dist/)
npm test           # vitest
npm run dev        # tsx watch mode

Source: src/server.ts (tool handlers), src/toolDefinitions.ts + src/router.ts (the 13-tool surface), src/tools/* (per-domain CRUD), src/utils/mapGenerator.ts (template cloning + procedural generation), src/intel/* (the read-only project-intelligence layer behind analyze_project), knowledge/ (static reference data + bundled maps).

License

MIT

RPG Maker MV Ultimate MCP Server

The 101 fine-grained v4 tool names still work as call aliases (set RPGMV_LEGACY_TOOLS=1 to also advertise them).

Install

The package ships an executable, so no clone is required. Add it to your MCP client:

hljs language-json

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

Works with Claude Desktop, Claude Code, opencode, and any MCP-compatible client. The server starts even without RPGMAKER_PROJECT_PATH — call set_project_path at runtime if you didn't set it.

From source

hljs language-bash

git clone https://github.com/DiegoLopez0208/RpgMakerMVUltimate-MCP
cd RpgMakerMVUltimate-MCP
npm install
npm run build
RPGMAKER_PROJECT_PATH=/path/to/your/project npm start

The 13 tools

Tool	Purpose
`query_database`	List / get by ID / search any database (actors, classes, skills, items, weapons, armors, enemies, states, troops, tilesets, common events, animations)
`create_database_entry`	Create entries, with presets: `damage_skill`, `healing_skill`, `buff_skill`, `state_skill`, `boss_enemy`, `encounter_troop`
`update_database_entry`	Partial updates (incl. troops & animations); append commands to common events; add enemies to troops
`delete_database_entry`	Delete entries incl. troops & animations (with reference-breakage warnings)
`query_map`	Map tree, full map data, events, single event, lint (`validate`), offline ASCII render
`generate_map`	Knowledge-driven generation: clones a real reference map per theme (or pure procedural / blank / themed / a specific template / batch / duplicate)
`edit_map`	Fill tile layers, set display names, organize the map tree, connect two maps, set encounters
`manage_map_event`	Create (presets: npc, chest, teleport, door, shop, inn, boss, puzzle_switch), update, convert an existing event into a merchant/inn/sign, delete, add commands, bulk-populate
`manage_system`	Game title, switch/variable names, starting position; author a plugin (`create_plugin`), scaffold a new project (`scaffold_project`), and run the game (`playtest`) / open it in the editor (`open_editor`)
`analyze_project`	Read-only project intelligence — `overview`, `index`, `validate`, `graph`, `usage`, `explain`, `ast`, `plugins`, `critique`, `refactor`, `search` (see below)
`get_project_context`	Project digest, asset index, per-tileset tile IDs, bundled-template catalog
`set_project_path`	Switch projects at runtime
`analyze_image`	Optional Vision-AI image analysis, plus offline tileset grid measurement and quadrant colors

Scaffold, run & write safety

Write safety. Every project write is atomic (temp file + rename, so an interrupted call can't leave half-written JSON) and keeps rotated timestamped backups under .mcp-backups/ (last N, RPGMV_BACKUP_KEEP, default 10). Pass dryRun: true to any mutating tool to preview the change without touching disk.
Scaffold a new project. manage_system { action: "scaffold_project", destPath, title? } clones the engine's blank template (NewData) into a new directory — the same thing the editor's New Project does — refusing to overwrite an existing project.
Run it. manage_system { action: "playtest" } launches the active project through the engine's bundled nwjs runtime (like the editor's Playtest button), so an agent can actually see a change running; open_editor opens it in RPGMV.exe. The install is found via install / the RPGMAKER_MV_INSTALL env var / the default Steam path (Windows).
Author plugins. manage_system { action: "create_plugin", name, ... } writes js/plugins/<name>.js with a correct @plugindesc/@param/@help header and registers it in js/plugins.js.

Map generation (knowledge-driven)

generate_map defaults to mode: "procedural", which is smarter than the name suggests:

For themes with a matching RTP reference template — town, village, dungeon, interior, castle, world, and more — it clones a hand-authored map from the 106 bundled templates, picking the closest size, so you get real 3D-looking buildings, walls and furniture instead of flat tile noise.
For themes without a template (beach, swamp, desert, …) it generates procedurally (Perlin terrain, BSP dungeons, cellular caves).
Same seed + params → the same map. Pass templateId to force a specific template, or useTemplate: false to force pure procedural.

hljs language-json

{
  "tool": "generate_map",
  "arguments": { "mode": "procedural", "theme": "town", "name": "Riverbend", "width": 40, "height": 30 }
}

Offline map inspection

No API needed:

query_map { view: "ascii", mapId } — render a map as a character grid with event markers (the cheapest way to "see" a layout and pick coordinates).
query_map { view: "validate", mapId } — lint for invalid tile IDs, broken transfers, and missing event terminators.

Project intelligence (`analyze_project`)

Read-only — it understands the whole project instead of re-reading files, so an agent can reason about a game it didn't build. All offline.

{ view: "overview" } — call this first on an unfamiliar project: counts, a health summary, and maps unreachable from the start.
{ view: "validate" } — every consistency problem at once: broken transfers, missing map files, dangling common-event/item/troop references, duplicate IDs, unused switches/variables, unreachable maps.
{ view: "explain", target: "switch", id } — why something never happens, e.g. "Switch 12 is read/gated in 3 places but is never set ON" (the usual cause of a door that never opens). target: "map" reports what a deletion would strand.
{ view: "usage", kind: "variable", id } — every event/common-event/troop that touches it (with read/write roles).
{ view: "graph" } — the map transfer network and reachability.
{ view: "ast", mapId, eventId } — an event's logic as a readable tree.
{ view: "plugins" } — what plugins the project uses, their parameters and commands.
{ view: "critique", mapId } — a designer-style review of one map (dead space, empty/cluttered, event spread, monotony) with justified suggestions.
{ view: "refactor" } — duplicated event logic worth extracting into a Common Event.
{ view: "search", query: "the blacksmith" } — find things by meaning across names, dialogue and descriptions.

Vision AI (optional)

Variable	Required	Description
`VISION_API_URL`	to enable	Base URL of the vision API (e.g. `https://api.openai.com`, `http://localhost:11434`). Unset = vision disabled.
`VISION_API_KEY`	optional	Bearer token; only sent when set.
`VISION_MODEL`	optional	Model name (default `meta/llama-3.2-90b-vision-instruct`).
`VISION_API_PATH`	optional	Endpoint path (default `/v1/chat/completions`).

hljs language-bash

# OpenAI
VISION_API_URL=https://api.openai.com VISION_API_KEY=sk-... VISION_MODEL=gpt-4o npm start
# Ollama (local, no key)
VISION_API_URL=http://localhost:11434 VISION_MODEL=llava npm start

Supported backends: OpenAI, Ollama, LocalAI, NVIDIA NIM, vLLM, LiteLLM, or any OpenAI-compatible proxy.

Agent Skill (recommended for any AI agent)

hljs language-bash

# Claude Code / Claude.ai
npx degit DiegoLopez0208/RpgMakerMVUltimate-MCP/skill/rpgmaker-mv-mcp ~/.claude/skills/rpgmaker-mv-mcp
# opencode
npx degit DiegoLopez0208/RpgMakerMVUltimate-MCP/skill/rpgmaker-mv-mcp ~/.opencode/skills/rpgmaker-mv-mcp

The skill is also listed in awesome-claude-skills.

Knowledge base

Static JSON reference data in knowledge/, extracted from the RPG Maker MV corescript and the bundled maps:

File	Content
`tile-ids.json`	Tile ID ranges, autotile formula, sheet descriptions
`passage-flags.json`	Flag bits, common flags, passage check logic
`event-commands.json`	~140 event command codes with parameter schemas
`enums.json`	Scope, occasion, hitType, damageType, restriction, etc.
`trait-effect-codes.json`	Trait codes 11-64, effect codes 11-45
`database-schemas.json`	Full schemas for all MV data types
`image-paths.json`	img/ directories, tileset slots, naming conventions
`map-templates.json`	Index of the 106 bundled reference maps
`stamps.json`	Mined multi-tile object stamps (trees, props) per tileset
`maps/`	106 RTP reference map JSONs used for template cloning

Feedback & contributing

Known limitations & roadmap

Decoration/object semantics are best-effort; rare multi-tile objects may be placed as single tiles.
Town and dungeon layouts keep improving — planned: central plaza/well landmark, houses in rows facing roads, fences/yards, richer road networks, more dungeon-room variety.
Vision AI is optional and requires your own endpoint.

Development

hljs language-bash

npm install
npm run build      # tsc compile (+ copies knowledge/ into dist/)
npm test           # vitest
npm run dev        # tsx watch mode

License

MIT

RpgMakerMVUltimate-MCP

RPG Maker MV Ultimate MCP Server

Install

From source

The 13 tools

Scaffold, run & write safety

Map generation (knowledge-driven)

Offline map inspection

Project intelligence (`analyze_project`)

Vision AI (optional)

Agent Skill (recommended for any AI agent)

Knowledge base

Feedback & contributing

Known limitations & roadmap

Development

License

Similar Packages

RpgMakerMVUltimate-MCP

RPG Maker MV Ultimate MCP Server

Install

From source

The 13 tools

Scaffold, run & write safety

Map generation (knowledge-driven)

Offline map inspection

Project intelligence (`analyze_project`)

Vision AI (optional)

Agent Skill (recommended for any AI agent)

Knowledge base

Feedback & contributing

Known limitations & roadmap

Development

License

Similar Packages

RpgMakerMVUltimate-MCP

RPG Maker MV Ultimate MCP Server

Install

From source

The 13 tools

Scaffold, run & write safety

Map generation (knowledge-driven)

Offline map inspection

Project intelligence (analyze_project)

Vision AI (optional)

Agent Skill (recommended for any AI agent)

Knowledge base

Feedback & contributing

Known limitations & roadmap

Development

License

Similar Packages

RpgMakerMVUltimate-MCP

RPG Maker MV Ultimate MCP Server

Install

From source

The 13 tools

Scaffold, run & write safety

Map generation (knowledge-driven)

Offline map inspection

Project intelligence (analyze_project)

Vision AI (optional)

Agent Skill (recommended for any AI agent)

Knowledge base

Feedback & contributing

Known limitations & roadmap

Development

License

Similar Packages

Project intelligence (`analyze_project`)

Project intelligence (`analyze_project`)