{
  "markdown": "# RPG Maker XP MCP Server\n\n**Build RPG Maker XP games by describing what you want.**\n\n> *\"Make a healing potion that restores 200 HP and costs 150 gold.\"*\n> *\"Create a 40×30 forest map with a pond in the north-east, then show it to me.\"*\n> *\"Find every NPC on map 3 whose dialogue mentions the king.\"*\n\nThis is an [MCP](#what-is-mcp) server that reads and writes an RPG Maker XP\nproject's `.rxdata` files directly — actors, skills, items, maps, events,\nscripts and system data — and renders map previews to PNG so you can see what\nwas built without opening the editor.\n\nIt talks to XP's native Ruby 1.8 Marshal format. Nothing is exported,\nconverted, or kept in a side file: it edits your real project, and the editor\nopens the result normally.\n\n---\n\n## ⚠️ Read this before your first run\n\n**1. Close the RPG Maker XP editor while the server is running.**\nThe editor holds all data files in memory and rewrites every one of them when\nyou save. If it is open, it will overwrite anything this server changed. This\nis the single most common way to lose work.\n\n**2. Back up your project first.** Copy the whole `Data/` folder somewhere\nsafe. Do this even though the server takes its own backups, because:\n\n**3. The automatic backup is not version history.** Before its first write to a\nfile in a session, the server copies the original to `Data/.mcp-backup/`. That\nis **one `.bak` per file per session** — the next session overwrites it. It\nprotects you from the last thing you did, not from something you broke a week\nago. If your project matters, put it in git.\n\n**4. Test your game after changes.** A file can be structurally valid and still\nbe wrong for your game.\n\n---\n\n## What is MCP?\n\nThe Model Context Protocol is a standard way for AI assistants to use external\ntools. This server is not a chat program and has no interface of its own — it\nis a backend that an **MCP client** connects to.\n\nYou need one of those clients. Common choices:\n\n- **[Claude Code](https://claude.com/claude-code)** — terminal-based\n- **[Claude Desktop](https://claude.ai/download)** — desktop app\n- **Open WebUI, Cursor, Windsurf, or any other MCP-capable client** — including\n  local models through Ollama ([see below](#using-a-local-model-via-ollama))\n\nIf you have never used an MCP client, start with Claude Desktop; the\n[Configuration](#configuration) section has a copy-paste config.\n\n---\n\n## Requirements\n\n| | |\n|---|---|\n| **Node.js** | 18 or newer |\n| **An MCP client** | Claude Desktop, Claude Code, or any MCP-capable app |\n| **An RPG Maker XP project** | a folder containing `Game.rxproj` and `Data/` |\n| **RPG Maker XP itself** | required if your project uses RTP assets |\n\nThe RTP (the default tiles, autotiles, character sprites and audio) is read\nfrom **your own installation** at runtime. This project does not bundle or\nredistribute any Enterbrain assets.\n\n### Does it work with Pokémon Essentials?\n\nStructurally, yes — Essentials games are RPG Maker XP projects, and every tool\nhere operates on standard `.rxdata`. Two honest caveats: Essentials layers its\nown conventions on top of the engine (its own data files, a very large\n`Scripts.rxdata`, PBS text files) which this server knows nothing about, and\nits projects are big enough that you should be especially sure about backup\npoint 2 above. Reading, map work and database edits behave normally.\n\n---\n\n## Installation\n\nThe published package ships prebuilt, so there is no build step. Most clients\ncan launch it on demand with `npx`.\n\n```bash\nnpm install -g rpgmaker-xp-mcp\n```\n\n<details>\n<summary><b>From source</b></summary>\n\n```bash\ngit clone https://github.com/SerifeusStudio/rpgmaker-xp-mcp.git\ncd rpgmaker-xp-mcp\nnpm install\nnpm run build\n```\n\nThen use `node` with the path to `dist/index.js` as the command in the configs\nbelow.\n</details>\n\n---\n\n## Configuration\n\nPoint the server at your project with `RPGMAKER_PROJECT_PATH` — the folder\ncontaining `Game.rxproj` and `Data/`. If your RTP lives somewhere unusual, also\nset `RPGMAKER_RTP_PATH`; it defaults to the Steam RPG Maker XP install.\n\n### Claude Code\n\n```bash\nclaude mcp add --scope user rpgmaker-xp \\\n  --env \"RPGMAKER_PROJECT_PATH=C:\\path\\to\\your\\project\" \\\n  -- npx -y rpgmaker-xp-mcp\n```\n\n### Claude Desktop\n\n`%APPDATA%\\Claude\\claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"rpgmaker-xp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"rpgmaker-xp-mcp\"],\n      \"env\": {\n        \"RPGMAKER_PROJECT_PATH\": \"C:/path/to/your/xp/project\"\n      }\n    }\n  }\n}\n```\n\nRestart the client, then check it connected by asking for something read-only:\n\n> *\"List the actors in my project.\"*\n\nIf you get names back, you are set up. See **[SETUP.md](SETUP.md)** for\ntroubleshooting.\n\n### Using a local model via Ollama\n\nThe server speaks standard MCP over stdio, so it works with any MCP client, not\nonly Claude. Ollama has no MCP client of its own yet, so a local model reaches\nit through a bridge.\n\n**Open WebUI** has native MCP support via\n[`mcpo`](https://github.com/open-webui/mcpo), an OpenAPI proxy. Save the same\n`mcpServers` block as `mcpo.json`, then:\n\n```bash\nuvx mcpo --port 8000 --config mcpo.json\n```\n\nRegister `http://localhost:8000/rpgmaker-xp` in Open WebUI as a tool server.\n\n**Terminal:** [`ollmcp`](https://github.com/jonigl/mcp-client-for-ollama)\nconnects MCP servers straight to a local Ollama model.\n\nPick a model with solid tool calling (a recent Qwen or Llama instruct model).\nSmaller models struggle to chain several calls reliably, which matters here —\nmap authoring is inherently multi-step.\n\n---\n\n## What it will *not* do\n\nWorth knowing before you install:\n\n- **XP only.** It does not read VX, VX Ace, MV or MZ projects. Their data\n  formats are different (`.rvdata`, `.rvdata2`, JSON).\n- **It does not generate art or audio.** It can import, classify and validate\n  graphics you already have; it cannot draw them.\n- **It does not write RGSS scripts for you** beyond storing what it is given —\n  it manages `Scripts.rxdata` as data, and correctness is on you and your model.\n- **It cannot run your game or test it.** `render_map` shows a static layout\n  preview, not gameplay.\n- **It does not know about Pokémon Essentials' own systems** (PBS files, its\n  plugin conventions, its data classes).\n\n---\n\n## Available tools (65)\n\n<details open>\n<summary><b>Actors</b></summary>\n\n`get_actors` · `get_actor` · `update_actor` · `create_actor` · `search_actors`\n\nXP actors use a `parameters` Table (6×100 — MaxHP, MaxSP, STR, DEX, AGI, INT\nper level) rather than MZ-style traits. `create_actor` generates linear growth\ncurves by default. Equipment slots are `weapon_id` and `armor1_id`–`armor4_id`\n(shield / helmet / body / accessory).\n</details>\n\n<details>\n<summary><b>Items & equipment</b></summary>\n\n`get_items` · `get_weapons` · `get_armors` · `get_skills` · `update_item` ·\n`search_items` · `create_weapon` · `create_armor`\n\n`create_weapon`/`create_armor` append to `Weapons.rxdata`/`Armors.rxdata` with\neditor-default fields (override any). Armor `kind`: 0=shield, 1=helmet, 2=body,\n3=accessory.\n</details>\n\n<details>\n<summary><b>Skills</b></summary>\n\n`get_skill` · `create_skill` · `create_damage_skill` · `create_healing_skill` ·\n`create_state_skill` · `update_skill` · `search_skills`\n\nXP has no damage formulas. Damage is `power` scaled by stat-influence rates\n(`atk_f`/`str_f` physical, `int_f` magical) and reduced by the target's\n`pdef_f`/`mdef_f`. **Negative power = healing.** There is no `create_buff_skill`\n— XP has no buff system, use states.\n\nScope: 0=none, 1=one enemy, 2=all enemies, 3=one ally, 4=all allies,\n5=one ally (HP 0), 6=all allies (HP 0), 7=user.\n</details>\n\n<details>\n<summary><b>Maps & events</b></summary>\n\n`get_map` · `get_map_infos` · `get_map_events` · `get_map_event` ·\n`update_map_event` · `create_map_event` · `create_transfer_event` ·\n`search_map_events` · `add_event_command` · `add_show_text`\n\nMaps live in `Data/MapXXX.rxdata`. `get_map` summarises the tile Table unless\n`includeTiles: true`. Events are a hash keyed by event ID.\n\n`add_show_text` handles XP's message structure (first line = code 101,\ncontinuations = 401, 4 lines per box). XP specifics: code 101 carries text\ndirectly (unlike VX+); choice text is stored redundantly in both the 102 array\nand the 402 branches and must stay in sync; move routes are 209/509.\n\n`create_transfer_event` wires two maps together and validates both endpoints\nexist and are in bounds before writing. Run `validate_connectivity` afterwards.\nThe full 110-code table is in [`research/event-commands.md`](research/event-commands.md).\n</details>\n\n<details>\n<summary><b>Map authoring (tile painting)</b></summary>\n\n`get_map_design_guide` · `get_map_size_advisory` · `create_map` ·\n`get_map_tiles` · `set_map_tiles` · `fill_region` · `apply_autotile` ·\n`scatter_tiles`\n\n`apply_autotile` paints an autotile and computes seamless edge variants per\ncell from 8-neighbour connectivity — give it an organic **`blob`** (ponds,\nlakes, forest), a **`cells`** list (rivers, curved paths), or a **`region`**\nrect (rectangular floors only). `scatter_tiles` distributes clutter at a target\ndensity with an optional focal gradient. Together these avoid the blocky ponds\nand corner-clustered detail that make maps look programmer-generated. See\n[MAP-DESIGN.md](MAP-DESIGN.md) §5b.\n\nLayers (`Map.data` z, drawn z0→z1→z2 = editor Layer 1/2/3) are assigned by\n**role**: z0 terrain (autotiles), z1 ground clutter (priority 0), z2 overhead\n(priority > 0 — canopies and roofs the player walks behind).\n\nTile ids: 0 = empty; 48–383 = autotiles (`slot=id/48-1`, `variant=id%48`);\n≥384 = regular tiles (`col=(id-384)%8`, `row=(id-384)/8`).\n\nLoad `get_map_design_guide` before authoring — `create_map` also returns its\ncore rules inline. `get_map_size_advisory` reports screen count, target focal\npoints, recommended scatter density and oversize warnings for an existing map.\n</details>\n\n<details>\n<summary><b>Validation</b></summary>\n\n`validate_assets` · `validate_connectivity`\n\n`validate_assets` scans every data file for referenced graphic and audio\nfilenames — tilesets, autotiles, panoramas, fogs, battlebacks, character,\nbattler and icon graphics, animations, windowskin, title, gameover, transition,\nBGM/BGS/ME and map event sprites — and reports any with no file on disk. Broken\nreferences are otherwise silent until runtime. Checks the project's `Graphics/`\nand `Audio/` first, then the RTP, matching base name regardless of extension.\n\n`validate_connectivity` builds the world transfer graph and reports maps\nunreachable from the start map, transfers pointing at a missing map or an\nout-of-bounds tile, and dead ends.\n</details>\n\n<details>\n<summary><b>Tileset identification & preview</b></summary>\n\n`create_tileset_identification_harness` · `get_tileset_catalog` ·\n`save_tileset_catalog` · `validate_tileset_catalog` · `render_tileset_atlas` ·\n`render_map`\n\n**`create_tileset_identification_harness`** builds an evidence-first review\nbundle: the source sheet, a labelled copy with burned-in tile IDs, isolated\ntransparent tile images, source rows, autotile sources, engine metadata, a\ncatalog template and an interactive browser page. Reviewed labels, intended\nuses, object grids, layers and confidence live in a **separate catalog**, so\npassability or visual resemblance cannot silently become a semantic claim. See\n[TILESET-CATALOG.md](TILESET-CATALOG.md).\n\n**`render_tileset_atlas`** renders a tileset to a labelled PNG — scaled with a\ngrid, each tile's id burned in, passability dots (red = blocked, orange =\npartial) and a legend of the 7 autotile slots.\n\n**`render_map`** renders a map's tile layers to a flat top-down **PNG preview**\noutside the editor, so you can *see* what you built. Composites all three\nlayers using the tileset graphic (ids ≥ 384) and its autotiles (ids 48–383, via\na cross-verified 48-variant quadrant table). Options: `layers`, `scale`,\n`region`, `drawGrid`, `drawEvents`, `passability`. Writes to\n`Data/.mcp-preview/map<NNN>.png` and returns the path.\n\n*Layout preview only* — no priority/overhead draw order, no fog, panorama or\nweather, and autotile animation uses frame 0.\n</details>\n\n<details>\n<summary><b>Asset import verification</b></summary>\n\n`classify_asset` · `verify_tileset` · `register_tileset`\n\nSorting a sheet by canvas dimensions alone silently mis-imports assets authored\nfor other engines, so these detect the true **content** tile size\n(edge-periodicity, where a candidate must evenly divide the canvas, biased\ntoward native 32px) and fingerprint the filename: a `$`/`!` prefix means a\nsingle-object sprite belonging in `Characters`, not a tileset; `A1`–`A5` means\nan MV/MZ autotile sheet *only* when content is not 32px, otherwise it is a\nbattler variant.\n\n`verify_tileset` writes a grid-overlay preview so scale problems are visible\nbefore import. `register_tileset` adds a guarded `Tilesets.rxdata` entry with\npassages/priorities/terrain Tables sized to the sheet, and declines non-native\nassets unless explicitly forced.\n</details>\n\n<details>\n<summary><b>Database, scripts & system</b></summary>\n\n**Database** — `get_database` · `get_database_entry` · `update_database_entry`\n\nGeneric access to every database file, including those without dedicated tools\n(Classes, States, Enemies, Troops, CommonEvents, Tilesets…). Tileset passability\nlives in the `passages` Table: 0 = passable; 1/2/4/8 = down/left/right/up\nblocked; 15 = impassable; +64 bush; +128 counter.\n\n**Scripts** — `get_scripts` · `get_script` · `update_script` · `create_script` ·\n`search_scripts`\n\nFull RGSS script access with zlib handling. Sources are stored as\n`[magic, name, zlib-deflated code]` triples; per-script magic numbers are not\nmeaningful to the editor. `create_script` inserts above `Main` by convention.\nBinary-safe — script data never passes through UTF-8 conversion.\n\n**System** — `get_system` · `get_variables` · `set_variable_name` ·\n`get_switches` · `set_switch_name` · `get_game_title` · `update_game_title` ·\n`update_starting_position`\n</details>\n\n---\n\n## How it works\n\n<details>\n<summary><b>The Marshal layer</b></summary>\n\n`.rxdata` files are parsed with a vendored, bug-fixed copy of\n[@hyrious/marshal](https://github.com/hyrious/marshal) (`src/vendor/marshal/`)\nand converted to plain JSON. Ruby objects become\n`{ \"_class\": \"RPG::Actor\", ... }` with instance variables as fields (no leading\n`@`).\n\n**Why vendored:** upstream ≤0.3.3 mis-decodes negative multibyte Marshal\nintegers — −150 decodes as +106. In XP, healing is negative power, so that bug\nsilently converted every healing skill into a damage skill on save. Details in\n[`research/REPORT.md`](research/REPORT.md).\n\nThe RGSS binary classes `Table` (tile and parameter grids), `Color` and `Tone`\nhave dedicated codecs. On save, strings are written as **raw byte strings** with\nno Ruby 1.9 encoding ivars, or XP's Ruby 1.8 / RGSS104E refuses to load them.\nThe game title lives in `Game.ini`, not in System data — unlike MZ.\n\nRound-trips of 15 of the 16 template `.rxdata` files from the RMXP install are\nbyte-identical. The exception is `Scripts.rxdata`, which the round-trip test\nexcludes rather than fails: it stores zlib-compressed source as *binary*\nstrings, so it needs the raw path (`readRxdataRaw`) instead of the UTF-8 one\nthe rest of the database uses. The script tools handle it correctly; only the\nround-trip test skips it.\n</details>\n\n<details>\n<summary><b>Behaviour that protects your project</b></summary>\n\n- **Automatic backups** — before the first write to any file in a session, the\n  original is copied to `Data/.mcp-backup/<name>.bak` (project root for\n  `Game.ini`). See the warning at the top: one per file per session.\n- **Save-revision marker** — map and event writes regenerate\n  `System.magic_number`, mirroring the editor, so existing save files reload the\n  changed map instead of keeping a stale copy.\n- **Event list invariants** — command lists are normalised on save: every\n  command gets code/indent/parameters, and the trailing\n  `{code: 0, indent: 0, parameters: []}` terminator is guaranteed.\n- **Verified engine math** — skill tools document XP's real damage algorithm,\n  extracted from `Game_Battler 3`, and the helpers are calibrated to\n  default-database conventions (heals are negative power with `int_f` 50).\n</details>\n\n<details>\n<summary><b>How conventions reach any client</b></summary>\n\nThe server surfaces its own guidance, so **any** MCP client gets the\nconventions — not just one that can read this repository:\n\n- **Server instructions** are sent on connect (governance + map-design rules)\n  and injected into context by most clients.\n- The guides are exposed as **MCP resources** (`rpgmaker-xp://docs/…`):\n  `map-design`, `tileset-catalog`, `authoring`, `wisdom`.\n- `get_map_design_guide` returns the full guide; `create_map` returns its core\n  rules inline.\n</details>\n\n---\n\n## Testing\n\n```bash\nnpm run build\nnode test/roundtrip.mjs        # Marshal round-trip against real RMXP data\nnode test/tools.mjs            # end-to-end tool tests on a scratch project\nnode test/server-smoke.mjs     # MCP stdio handshake + tool calls\nnode test/render.mjs           # renderer: autotile table + PNG renders\nnode test/tileset-catalog.mjs  # catalog validation\nnode test/authoring.mjs        # map authoring primitives\nnode test/connectivity.mjs     # transfer-graph validation\nnode test/validate.mjs         # asset reference checking\nnode test/extract-scripts.mjs  # Scripts.rxdata extraction\n```\n\nThe round-trip test loads every `.rxdata` file from the RMXP install's\nnew-project template, converts to JSON and back, and verifies byte-identical\noutput. Render tests need local RMXP graphics (the Steam RTP install and the\n`library/Valentine90-ABS` fixture) and **skip** rather than fail when those are\nabsent; the autotile-table integrity check always runs.\n\n---\n\n## Documentation\n\n| Document | What it covers |\n|---|---|\n| **[SETUP.md](SETUP.md)** | Install and configuration walkthrough, troubleshooting |\n| **[EXAMPLES.md](EXAMPLES.md)** | Worked examples — what to ask for, and the tool calls it produces |\n| **[AUTHORING-XP.md](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 |\n| **[MAP-DESIGN.md](MAP-DESIGN.md)** | Level design: the three-layer model, priority and passability, multi-tile object rules, composition |\n| **[SKILL_CREATION_GUIDE.md](SKILL_CREATION_GUIDE.md)** | XP's damage model in depth, and the skill creation tools |\n| **[TILESET-CATALOG.md](TILESET-CATALOG.md)** | Evidence-first tile identification, object grouping, confidence rules |\n| **[CONTENT-SOURCES.md](CONTENT-SOURCES.md)** | Licence-vetted catalogue of RGSS1 script libraries you can install with `create_script` |\n| **[WISDOM.md](WISDOM.md)** | Collected engineering notes: Marshal layer, battle math, event system, coexisting with the editor |\n| **[research/](research/)** | Event command table, RGSS class definitions, the decoder bug report |\n\n---\n\n## Credits\n\nForked from **[k4zuki0539/-rpgmaker-mz-mcp](https://github.com/k4zuki0539/-rpgmaker-mz-mcp)**\n(RPG Maker MZ MCP Server, MIT), then re-authored for RPG Maker XP. The MZ\nversion targets MZ's JSON data; this fork reads and writes XP's Ruby 1.8\nMarshal `.rxdata` directly, and adds skills, scripts, database and render\ntooling, a byte-verified Marshal codec, map authoring and map rendering.\nUpstream authorship and the MIT licence are preserved — see [`LICENSE`](LICENSE).\n\nMaintained by **[SerifeusStudios](https://github.com/SerifeusStudio)**.\nThird-party components and their licences are listed in\n[`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md).\n\nRPG Maker XP is a product of Enterbrain / Gotcha Gotcha Games. This project is\nunaffiliated, and bundles no engine assets.\n\n## License\n\nMIT — © 2025 k4zuki0539 (original MZ MCP) and © 2026 SerifeusStudios (XP fork).\nSee [`LICENSE`](LICENSE) and [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md).\n",
  "bytes": 19947,
  "sha": "375756a41293f46b6d3060aca2e41261df5f73c46cb410053a3cc5e1a948d144",
  "repo_slug": "serifeusstudio/rpgmaker-xp-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_serifeusstudio_rpgmaker_xp_mcp_22e4d682/readme"
}