rpgmaker-mv-mcp

Driving the RPG Maker MV MCP correctly

This MCP edits a real RPG Maker MV project on disk (data/*.json, validated against the actual engine). It is powerful but the engine is unforgiving: a wrong tile ID, a sprite that doesn't exist, or a missing field crashes the game. Follow this workflow and you produce coherent, playable content; ignore it and you produce "random tiles everywhere" and Loading-Error crashes.

The one rule that prevents 90% of bad output

Do NOT hand-paint tiles or place objects one tile at a time, and never invent IDs. Build maps with generate_map and add content with the manage_map_event presets. generate_map is knowledge-driven: for most themes it clones a real hand-authored reference map from the 106 bundled templates (real multi-tile houses, walls, furniture) instead of painting tiles procedurally, so the output looks like a real RPG Maker map and only uses IDs that exist. When you do need an ID (tile, sprite, troop, skill, item), get it from get_project_context — never guess.

Standard workflow

1. get_project_context (detail full) — ALWAYS first. Returns every database id+name, switch/variable names, starting position, and the sprite filenames available per img/ folder. This is your source of truth; read it before creating anything.
2. Build the world with generate_map (default mode:"procedural", which is knowledge-driven):
   • Pick a theme (town, village, forest, dungeon, cave, world, interior, castle, beach, desert, snow, …) and omit tilesetId — it auto-selects the right tileset. For themes with a bundled reference map (town, village, dungeon, interior, castle, world, …) it clones a real hand-authored map from the knowledge base, adapted to your tilesets; for themes without one (beach, swamp, desert) it generates procedurally. Combat themes auto-wire random encounters from existing troops.
   • Want a specific reference map? List them with get_project_context detail:"templates", then generate_map mode:"template" templateId:<id> (or pass templateId in procedural mode to force that one). Force pure procedural generation with useTemplate:false. Same seed + params → the same map.
   • town/village auto-create enterable house interiors with two-way warps (returned in interiorMapIds); opt out with enterableHouses:false.
   • To connect maps, use edit_map action:"connect" (bidirectional) or manage_map_event preset:"door" / "teleport".
3. Populate with manage_map_event presets (each builds a complete, working event):
   • npc {dialogues[], characterName?, characterIndex?} — characterName must be a real sprite from get_project_context (e.g. People1); omit for invisible.
   • chest {items:[{type:item|weapon|armor,id,amount}]} — IDs must exist (check first).
   • shop {goods:[[type,id,priceType,price]]}, inn {cost}, boss {troopId}, teleport/door {destMapId,destX,destY}, puzzle_switch.
4. Database via create_database_entry / update_database_entry / query_database (entity = actors/classes/skills/items/weapons/armors/enemies/states/troops/common_events). Presets exist for skills (damage_skill, healing_skill, …), boss_enemy, encounter_troop.
5. System: manage_system for title, switch/variable names, and set_starting_position (validate the map exists first).