SerifeusStudio/rpgmaker-xp-mcp

**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** — 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.
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.
From source
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 Desktop
%APPDATA%\Claude\claude_desktop_config.json:
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: