RPG Maker XP / Pokémon Essentials MCP Server

Build RPG Maker XP and Pokémon Essentials games by describing what you want.

"Make a healing potion that restores 200 HP and costs 150 gold." "Copy the lab building from Lappet Town into my new map and wire its door up." "Can the player actually reach every exit on map 12?" "Find every event 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 edits your real project in place — nothing is exported, converted, or kept in a side file, and the editor opens the result normally.

This is a fork of rpgmaker-xp-mcp that adds first-class Pokémon Essentials support and a set of tools for seeing and checking your work — a map preview you can read coordinates off, a reachability check that tells you whether the player can actually get to a door, and a linter for the ways XP maps go quietly wrong.

⚠️ 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.

5. Pokémon Essentials only recompiles in Debug mode. If you edit PBS/*.txt or anything in Plugins/, launch the game once from the editor (or a debug build) — outside Debug mode those changes are silently ignored. Map and event edits made by this server are not affected and take effect immediately.

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 — terminal-based
• Claude Desktop — 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

| | | |---|---| | Node.js | 18 or newer | | An MCP client | Claude Desktop, Claude Code, or any MCP-capable app | | An RPG Maker XP project | a folder containing Game.rxproj and Data/ | | RPG Maker XP itself | required if your project uses RTP assets |

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.

Pokémon Essentials

Yes — that is what this fork is for. Essentials games are RPG Maker XP projects, and the upstream server could not read most of their maps: any map containing an accented character (so, nearly all of them in a Pokémon game) failed to load. That is fixed here, along with several ways a save could quietly corrupt text encoding, hash ordering or shared data.

Two things it still does not know about, and you need to:

PBS files are the source of truth for game data. Species, moves, items, trainers and encounters live in PBS/*.txt, not in .rxdata. This server does not edit them. If you change a PBS file, the game only recompiles it in Debug mode — launch from the editor or a debug build once, or delete the matching Data/*.dat, otherwise your change is silently ignored.

Essentials replaces the whole script suite. Scripts.rxdata holds ~400 scripts. You can read and search them here, but new behaviour belongs in the Plugins/ folder, which loads after the core scripts and survives an Essentials upgrade. Plugins also only compile in Debug mode.

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-pkmn-essentials-mcp

git clone https://github.com/nmccray01/rpgmaker-pkmn-essentials-mcp.git
cd rpgmaker-pkmn-essentials-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-pkmn-essentials-mcp

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "rpgmaker-xp": {
      "command": "npx",
      "args": ["-y", "rpgmaker-pkmn-essentials-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 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 edit Pokémon Essentials' PBS files or plugins. It reads and writes the RPG Maker side; species, moves, items and trainers live in PBS/*.txt and are yours to edit (see above).

Available tools (67)

get_database · get_database_entry · update_actor · create_actor · search_database

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).

get_database · get_database_entry · update_item · search_database · 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.

create_skill · create_damage_skill · create_healing_skill · create_state_skill · update_skill · get_database_entry · search_database

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.

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.

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.

render_map · render_tiles · analyze_passability

render_map renders a map's layers to a flat top-down PNG so you can see the result without opening the editor. Set coords: 5 to burn tile x/y numbers into the image every 5 tiles — without them a picture cannot be tied back to a coordinate, which is what you need to act on it. Other options: layers, scale, region, drawGrid, drawEvents, passability.

render_tiles answers "which tile is the door?". Give it specific ids ([385, "800-809", 1346]) or a filter (e.g. every passable, priority-0, terrain-0 tile = plain walkable ground) and it returns a small labelled contact sheet plus each tile's passability, priority and terrain tag as data — so tiles get chosen from facts rather than by squinting at pixels. Omit both and you get the whole tileset, paginated.

analyze_passability flood-fills a map using the engine's real movement rules and tells you what the player can actually reach: reachable / walkable / cut-off counts, disconnected pockets, an ASCII map, and every transfer event with whether it can be reached. Run it after building a map and you will know the exits work without launching the game.

copy_region · manage_objects · stamp_object · clone_event · retarget_transfers · edit_event_pages

Composing a building out of raw tile ids is guesswork; copying one out of a map that already looks right is not.

copy_region copies a rectangle of tiles between maps and warns when it overwrites something on the same layer — that overlap is how multi-tile objects end up clipped. manage_objects saves such a rectangle under a name with named anchors ({ door: [3,4] }), and stamp_object places it and tells you where each anchor landed in absolute coordinates, so the door event goes down without recomputing offsets.

clone_event deep-copies an event onto another map and can retarget its transfer in the same call. This matters most for doors: a Pokémon Essentials door is two pages and ~60 commands of door animation, follower handling, screen fade and an arrival page — clone the one your project already ships rather than trying to rebuild it.

edit_event_pages makes structured page edits (add / insert / remove a page, set its condition, graphic, trigger, text, or individual commands). Remember that RPG Maker runs the last page whose conditions are met, so a more specific state belongs after a more general one. If any edit in a batch fails, nothing is written.

search_events · find_tiles · tile_histogram · diff_map · manage_backups

search_events finds events by what they contain — name, a regex over dialogue, a command code, a transfer destination, a page graphic — instead of reading whole maps. Asking for everything that transfers into a map is the quickest way to find every door into it.

find_tiles locates a tile id across the project; tile_histogram reports a map's tile vocabulary, which is the fastest way to borrow a palette that matches the rest of your game.

diff_map shows what changed on a map — tile edits with from/to per cell, and events added, removed, moved or edited. By default it compares against the session backup, so it answers "what have my edits done so far?". manage_backups lists those backups (flagging which files this session changed) and can restore one. A file the session created has no backup, since there was nothing to preserve — delete it instead.

validate_assets · validate_connectivity · lint_map

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.

lint_map checks one map — or the whole project, if you omit mapId — for the specific ways XP maps go quietly wrong: tiles painted with an autotile slot that has no graphic (they draw nothing but still block, which is the classic invisible wall), transfers into a missing map / off the edge / onto a wall, tile ids past the end of the tileset, and message text containing a real control byte where a message code was meant.

Its rules are deliberately tuned for precision: a whole shipped Essentials project lints clean. Findings marked info — such as the list of invisible collision blockers on a map — are things to glance at, not defects, and do not count against ok.

create_tileset_identification_harness · get_tileset_catalog · save_tileset_catalog · validate_tileset_catalog

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.

For previewing tiles and maps see Seeing what you built above.

classify_asset · verify_tileset · register_tileset

Sorting a sheet by canvas dimensions alone silently mis-imports assets authored for other engines, so these detect the true content tile size (edge-periodicity, where a candidate must evenly divide the canvas, biased toward native 32px) and fingerprint the filename: a $/! prefix means a single-object sprite belonging in Characters, not a tileset; A1–A5 means an MV/MZ autotile sheet only when content is not 32px, otherwise it is a battler variant.

verify_tileset writes a grid-overlay preview so scale problems are visible before import. register_tileset adds a guarded Tilesets.rxdata entry with passages/priorities/terrain Tables sized to the sheet, and declines non-native assets unless explicitly forced.

Database — get_database · get_database_entry · update_database_entry

Generic access to every database file, including those without dedicated tools (Classes, States, Enemies, Troops, CommonEvents, Tilesets…). Tileset passability lives in the passages Table: 0 = passable; 1/2/4/8 = down/left/right/up blocked; 15 = impassable; +64 bush; +128 counter.

Scripts — get_scripts · get_script · update_script · create_script · search_scripts

Full RGSS script access with zlib handling. Sources are stored as [magic, name, zlib-deflated code] triples; per-script magic numbers are not meaningful to the editor. create_script inserts above Main by convention. Binary-safe — script data never passes through UTF-8 conversion.

System — get_system · get_symbols · set_symbol_name · get_game_title · update_game_title · update_starting_position

get_symbols lists every named switch and variable in one call. Read it before inventing new ones — a project usually already has what you need (an Essentials project ships Choosing starter and Starter choice), and reusing them keeps the existing event logic working.

How it works

.rxdata files are parsed with a vendored, bug-fixed copy of @hyrious/marshal (src/vendor/marshal/) and converted to plain JSON. Ruby objects become { "_class": "RPG::Actor", ... } with instance variables as fields (no leading @).

Why vendored: upstream ≤0.3.3 mis-decodes negative multibyte Marshal integers — −150 decodes as +106. In XP, healing is negative power, so that bug silently converted every healing skill into a damage skill on save. Details in research/REPORT.md.

The RGSS binary classes Table (tile and parameter grids), Color and Tone have dedicated codecs. On save, strings are written as raw byte strings with no Ruby 1.9 encoding ivars, or XP's Ruby 1.8 / RGSS104E refuses to load them. The game title lives in Game.ini, not in System data — unlike MZ.

Round-trips of 15 of the 16 template .rxdata files from the RMXP install are byte-identical. The exception is Scripts.rxdata, which the round-trip test excludes rather than fails: it stores zlib-compressed source as binary strings, so it needs the raw path (readRxdataRaw) instead of the UTF-8 one the rest of the database uses. The script tools handle it correctly; only the round-trip test skips it.

• Automatic backups — before the first write to any file in a session, the original is copied to Data/.mcp-backup/<name>.bak (project root for Game.ini). See the warning at the top: one per file per session.
• Save-revision marker — map and event writes regenerate System.magic_number, mirroring the editor, so existing save files reload the changed map instead of keeping a stale copy.
• Event list invariants — command lists are normalised on save: every command gets code/indent/parameters, and the trailing {code: 0, indent: 0, parameters: []} terminator is guaranteed.
• Verified engine math — skill tools document XP's real damage algorithm, extracted from Game_Battler 3, and the helpers are calibrated to default-database conventions (heals are negative power with int_f 50).

The server surfaces its own guidance, so any MCP client gets the conventions — not just one that can read this repository:

• Server instructions are sent on connect (governance + map-design rules) and injected into context by most clients.
• The guides are exposed as MCP resources (rpgmaker-xp://docs/…): map-design, tileset-catalog, authoring, wisdom.
• get_map_design_guide returns the full guide; create_map returns its core rules inline.

Testing

npm run build
node test/roundtrip.mjs             # Marshal round-trip against the RMXP template
node test/roundtrip-essentials.mjs  # byte-exact round-trip over a real project
node test/tools.mjs                 # end-to-end tool tests on a scratch project
node test/analysis.mjs              # passability + message checking
node test/authoring-primitives.mjs  # copy/clone/page-edit/object catalog
node test/lint.mjs                  # lint_map precision and recall
node test/history.mjs               # diff, backups, event search
node test/server-smoke.mjs     # MCP stdio handshake + tool calls
node test/render.mjs           # renderer: autotile table + PNG renders
node test/tileset-catalog.mjs  # catalog validation
node test/authoring.mjs        # map authoring primitives
node test/connectivity.mjs     # transfer-graph validation
node test/validate.mjs         # asset reference checking
node test/extract-scripts.mjs  # Scripts.rxdata extraction

npm run test:all runs the four newest suites; they build their own synthetic projects and need no RPG Maker install.

The round-trip tests load .rxdata files, convert to JSON and back, and verify byte-identical output — roundtrip-essentials.mjs does this over a real project (point it at <project>/Data), which is the check that keeps saving a file from quietly rewriting parts you never touched. Render tests need local RMXP graphics (the Steam RTP install and the library/Valentine90-ABS fixture) and skip rather than fail when those are absent; the autotile-table integrity check always runs.

Documentation

| Document | What it covers | |---|---| | SETUP.md | Install and configuration walkthrough, troubleshooting | | EXAMPLES.md | Worked examples — what to ask for, and the tool calls it produces | | AUTHORING-XP.md | Writing for XP, and how this server acts as a governance layer to keep a project canonical as humans and models both edit it | | MAP-DESIGN.md | Level design: the three-layer model, priority and passability, multi-tile object rules, composition | | SKILL_CREATION_GUIDE.md | XP's damage model in depth, and the skill creation tools | | TILESET-CATALOG.md | Evidence-first tile identification, object grouping, confidence rules | | CONTENT-SOURCES.md | Licence-vetted catalogue of RGSS1 script libraries you can install with create_script | | WISDOM.md | Collected engineering notes: Marshal layer, battle math, event system, coexisting with the editor | | research/ | Event command table, RGSS class definitions, the decoder bug report | | docs/ | What this fork added and why, with the reference implementations behind it |

Credits

Built and maintained by nmccray01.

This server targets RPG Maker XP and Pokémon Essentials: it reads and writes XP's Ruby Marshal .rxdata directly, decodes the string encodings that made most Essentials maps unreadable, and preserves encodings, hash order and shared data across a save. On top of that it adds the tooling this README documents — previewing and verifying map work (render_tiles, analyze_passability, lint_map), building by reuse (copy_region, clone_event, stamp_object, edit_event_pages) and reviewing changes (diff_map, search_events, manage_backups).

Derived, via rpgmaker-xp-mcp (© SerifeusStudios), from k4zuki0539/-rpgmaker-mz-mcp (© k4zuki0539) — both MIT. Those copyright notices are retained in LICENSE, as MIT requires.

Third-party components, including the vendored Marshal codec derived from @hyrious/marshal (© hyrious, MIT), are listed in THIRD-PARTY-NOTICES.md.

RPG Maker XP is a product of Enterbrain / Gotcha Gotcha Games. This project is unaffiliated, and bundles no engine assets.

License

MIT — © 2025 k4zuki0539 (original MZ MCP) and © 2026 SerifeusStudios (XP fork). See LICENSE and THIRD-PARTY-NOTICES.md.