Rpgmaker Xp MCP

RPG Maker XP MCP Server

Build RPG Maker XP games by describing what you want.

*"Make a healing potion that restores 200 HP and costs 150 gold."*

*"Create a 40×30 forest map with a pond in the north-east, then show it to me."*

*"Find every NPC on map 3 whose dialogue mentions the king."*

This is an MCP server that reads and writes an RPG Maker XP project's .rxdata files directly — actors, skills, items, maps, events, scripts and system data — and renders map previews to PNG so you can see what was built without opening the editor.

It talks to XP's native Ruby 1.8 Marshal format. Nothing is exported, converted, or kept in a side file: it edits your real project, and the editor opens the result normally.

⚠️ Read this before your first run

1. Close the RPG Maker XP editor while the server is running. The editor holds all data files in memory and rewrites every one of them when you save. If it is open, it will overwrite anything this server changed. This is the single most common way to lose work.

2. Back up your project first. Copy the whole Data/ folder somewhere safe. Do this even though the server takes its own backups, because:

3. The automatic backup is not version history. Before its first write to a file in a session, the server copies the original to Data/.mcp-backup/. That is one `.bak` per file per session — the next session overwrites it. It protects you from the last thing you did, not from something you broke a week ago. If your project matters, put it in git.

4. Test your game after changes. A file can be structurally valid and still be wrong for your game.

What is MCP?

The Model Context Protocol is a standard way for AI assistants to use external tools. This server is not a chat program and has no interface of its own — it is a backend that an MCP client connects to.

You need one of those clients. Common choices:

• [Claude Code](https://claude.com/claude-code) — terminal-based
• [Claude Desktop](https://claude.ai/download) — desktop app
• Open WebUI, Cursor, Windsurf, or any other MCP-capable client — including local models through Ollama (see below)

If you have never used an MCP client, start with Claude Desktop; the Configuration section has a copy-paste config.

Requirements

The RTP (the default tiles, autotiles, character sprites and audio) is read from your own installation at runtime. This project does not bundle or redistribute any Enterbrain assets.

Does it work with Pokémon Essentials?

Structurally, yes — Essentials games are RPG Maker XP projects, and every tool here operates on standard .rxdata. Two honest caveats: Essentials layers its own conventions on top of the engine (its own data files, a very large Scripts.rxdata, PBS text files) which this server knows nothing about, and its projects are big enough that you should be especially sure about backup point 2 above. Reading, map work and database edits behave normally.

Installation

The published package ships prebuilt, so there is no build step. Most clients can launch it on demand with npx.

npm install -g rpgmaker-xp-mcp

From source

git clone https://github.com/SerifeusStudio/rpgmaker-xp-mcp.git

cd rpgmaker-xp-mcp npm install npm run build

Then use node with the path to dist/index.js as the command in the configs below.

Configuration

Point the server at your project with RPGMAKER_PROJECT_PATH — the folder containing Game.rxproj and Data/. If your RTP lives somewhere unusual, also set RPGMAKER_RTP_PATH; it defaults to the Steam RPG Maker XP install.

Claude Code

claude mcp add --scope user rpgmaker-xp \

--env "RPGMAKER_PROJECT_PATH=C:\path\to\your\project" \ -- npx -y rpgmaker-xp-mcp

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json:

{

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

Restart the client, then check it connected by asking for something read-only:

*"List the actors in my project."*

If you get names back, you are set up. See [SETUP.md](SETUP.md) for troubleshooting.

Using a local model via Ollama

The server speaks standard MCP over stdio, so it works with any MCP client, not only Claude. Ollama has no MCP client of its own yet, so a local model reaches it through a bridge.

Open WebUI has native MCP support via mcpo, an OpenAPI proxy. Save the same mcpServers block as mcpo.json, then:

uvx mcpo --port 8000 --config mcpo.json

Register http://localhost:8000/rpgmaker-xp in Open WebUI as a tool server.

Terminal: ollmcp connects MCP servers straight to a local Ollama model.

Pick a model with solid tool calling (a recent Qwen or Llama instruct model). Smaller models struggle to chain several calls reliably, which matters here — map authoring is inherently multi-step.

What it will *not* do

Worth knowing before you install:

• XP only. It does not read VX, VX Ace, MV or MZ projects. Their data formats are different (.rvdata, .rvdata2, JSON).
• It does not generate art or audio. It can import, classify and validate graphics you already have; it cannot draw them.
• It does not write RGSS scripts for you beyond storing what it is given — it manages Scripts.rxdata as data, and correctness is on you and your model.
• It cannot run your game or test it. render_map shows a static layout preview, not gameplay.
• It does not know about Pokémon Essentials' own systems (PBS files, its plugin conventions, its data classes).

Available tools (65)

Actors

get_actors · get_actor · update_actor · create_actor · search_actors

XP actors use a parameters Table (6×100 — MaxHP, MaxSP, STR, DEX, AGI, INT per level) rather than MZ-style traits. create_actor generates linear growth curves by default. Equipment slots are weapon_id and armor1_id–armor4_id (shield / helmet / body / accessory).

Items & equipment

get_items · get_weapons · get_armors · get_skills · update_item · search_items · create_weapon · create_armor

create_weapon/create_armor append to Weapons.rxdata/Armors.rxdata with editor-default fields (override any). Armor kind: 0=shield, 1=helmet, 2=body, 3=accessory.

Skills

get_skill · create_skill · create_damage_skill · create_healing_skill · create_state_skill · update_skill · search_skills

XP has no damage formulas. Damage is power scaled by stat-influence rates (atk_f/str_f physical, int_f magical) and reduced by the target's pdef_f/mdef_f. Negative power = healing. There is no create_buff_skill — XP has no buff system, use states.

Scope: 0=none, 1=one enemy, 2=all enemies, 3=one ally, 4=all allies, 5=one ally (HP 0), 6=all allies (HP 0), 7=user.

Maps & events

get_map · get_map_infos · get_map_events · get_map_event · update_map_event · create_map_event · create_transfer_event · search_map_events · add_event_command · add_show_text

Maps live in Data/MapXXX.rxdata. get_map summarises the tile Table unless includeTiles: true. Events are a hash keyed by event ID.

add_show_text handles XP's message structure (first line = code 101, continuations = 401, 4 lines per box). XP specifics: code 101 carries text directly (unlike VX+); choice text is stored redundantly in both the 102 array and the 402 branches and must stay in sync; move routes are 209/509.

create_transfer_event wires two maps together and validates both endpoints exist and are in bounds before writing. Run validate_connectivity afterwards. The full 110-code table is in research/event-commands.md.

Map authoring (tile painting)

get_map_design_guide · get_map_size_advisory · create_map · get_map_tiles · set_map_tiles · fill_region · apply_autotile · scatter_tiles

apply_autotile paints an autotile and computes seamless edge variants per cell from 8-neighbour connectivity — give it an organic `blob` (ponds, lakes, forest), a `cells` list (rivers, curved paths), or a `region` rect (rectangular floors only). scatter_tiles distributes clutter at a target density with an optional focal gradient. Together these avoid the blocky ponds and corner-clustered detail that make maps look programmer-generated. See MAP-DESIGN.md §5b.

Layers (Map.data z, drawn z0→z1→z2 = editor Layer 1/2/3) are assigned by role: z0 terrain (autotiles), z1 ground clutter (priority 0), z2 overhead (priority > 0 — canopies and roofs the player walks behind).

Tile ids: 0 = empty; 48–383 = autotiles (slot=id/48-1, variant=id%48); ≥384 = regular tiles (col=(id-384)%8, row=(id-384)/8).

Load get_map_design_guide before authoring — create_map also returns its core rules inline. get_map_size_advisory reports screen count, target focal points, recommended scatter density and oversize warnings for an existing map.

Validation

validate_assets · validate_connectivity

validate_assets scans every data file for referenced graphic and audio filenames — tilesets, autotiles, panoramas, fogs, battlebacks, character, battler and icon graphics, animations, windowskin, title, gameover, transition, BGM/BGS/ME and map event sprites — and reports any with no file on disk. Broken references are otherwise silent until runtime. Checks the project's Graphics/ and Audio/ first, then the RTP, matching base name regardless of extension.

validate_connectivity builds the world transfer graph and reports maps unreachable from the start map, transfers pointing at a missing map or an out-of-bounds tile, and dead ends.

Tileset identification & preview

create_tileset_identification_harness · get_tileset_catalog · save_tileset_catalog · validate_tileset_catalog · render_tileset_atlas · render_map

`create_tileset_identification_harness` builds an evidence-first review bundle: the source sheet, a labelled copy with burned-in tile IDs, isolated transparent tile images, source rows, autotile sources, engine metadata, a catalog template and an interactive browser page. Reviewed labels, intended uses, object grids, layers and confidence live in a separate catalog, so passability or visual resemblance cannot silently become a semantic claim. See TILESET-CATALOG.md.

`render_tileset_atlas` renders a tileset to a labelled PNG — scaled with a grid, each tile's id burned in, passability dots (red = blocked, orange = partial) and a legend of the 7 autotile slots.

`render_map` renders a map's tile layers to a flat top-down PNG preview outside the editor, so you can *see* what you built. Composites all three layers using the tileset graphic (ids ≥ 384) and its autotiles (ids 48–383, via a cross-verified 48-variant quadrant table). Options: layers, scale, region, drawGrid, drawEvents, passability. Writes to Data/.mcp-preview/map .png and returns the path.

*Layout p