{
  "markdown": "# RPG Maker MV MCP Server\n\n[![CI](https://github.com/Xerolo44/RPG-Maker-MV-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Xerolo44/RPG-Maker-MV-MCP/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)\n[![MCP](https://img.shields.io/badge/protocol-Model%20Context%20Protocol-blueviolet)](https://modelcontextprotocol.io)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server that turns AI assistants\n(Claude Code, Claude Desktop, or any MCP client) into a co-developer for **RPG Maker MV**\nprojects — with automatic backups of everything it touches.\n\nAsk your assistant things like:\n\n> *\"Create a Fireball skill: magical damage, `a.mat * 4 - b.mdf * 2`, 12 MP, fire element.\"*\n> *\"Find every event in the game that mentions the mayor.\"*\n> *\"Add a guard to the castle gate who says 'Halt! Who goes there?'\"*\n> *\"Rebalance all weapons: +10% attack across the board.\"*\n> *\"Validate the project — anything broken?\"*\n\n## Highlights\n\n- **Full database access** — all 12 database types (actors, classes, skills, items, weapons,\n  armors, enemies, troops, states, animations, tilesets, common events) plus System.json,\n  through a compact generic CRUD interface.\n- **High-level skill builders** — create complete, editor-valid damage / healing / buff /\n  state skills from just a name and a formula.\n- **Maps and events** — create maps, create/edit/delete events, insert event commands in\n  batches, add dialogue with automatic message-box splitting, and consult a built-in\n  event command code reference.\n- **Search everywhere** — substring search across every database, and across every event on\n  every map, including *inside* event command lists (find which event shows a line of\n  dialogue or runs a script).\n- **Plugin management** — enable/disable/configure plugins, scaffold new ones, edit plugin\n  source, all in the editor's own `js/plugins.js` format.\n- **Playtest control** — launch the game through NW.js (auto-detected from common install\n  locations) with stdout/stderr capture, or serve it to a browser via the built-in HTTP server.\n- **Safety net** — every file is snapshotted to `.mcp-backups/` before its first modification\n  each session; `restore_backup` rolls anything back, and `validate_project` catches broken\n  references before you ship.\n\n## Installation\n\nRequires Node.js 18+.\n\n### Quick start (npm)\n\nThe easiest way for Claude Code or Claude Desktop users:\n\n```sh\nnpm install -g @xerolo44/rpgmaker-mv-mcp\n```\n\nThen configure it (see below). The package is available on [npmjs.com](https://www.npmjs.com/package/@xerolo44/rpgmaker-mv-mcp) and in the [MCP Registry](https://registry.modelcontextprotocol.io/).\n\n### Configure Claude Code\n\n```sh\nclaude mcp add rpgmaker-mv -- npx @xerolo44/rpgmaker-mv-mcp --project \"/path/to/YourGame\"\n```\n\n### Configure Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"rpgmaker-mv\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@xerolo44/rpgmaker-mv-mcp\",\n        \"--project\", \"/path/to/YourGame\"\n      ]\n    }\n  }\n}\n```\n\n`--project` is optional — without it, ask the assistant to call `set_project` first. The\nproject can also be switched mid-session.\n\n### Custom connector / URL-based clients (HTTPS) — experimental\n\nSome clients (e.g. \"Add custom connector\" UIs) don't spawn a local process — they connect\nto a URL instead. Run the server in HTTPS mode:\n\n```sh\nnode dist/index.js --http [port]   # default port 3939\n```\n\nThis starts a Streamable HTTP MCP endpoint at `https://127.0.0.1:<port>/mcp`, bound to\nlocalhost only (never reachable from the network — every request is checked against the\nconnecting socket's address, not just the bind address). A self-signed TLS certificate for\n`localhost`/`127.0.0.1` is generated on first run and cached in `.certs/` (gitignored) next\nto the project.\n\n**Status:** the endpoint is fully verified at the protocol level (handshake, session\nmanagement, and all 41 tools tested directly over HTTPS with `curl`). What's *not*\nguaranteed is that a given GUI connector-adding flow will accept a self-signed localhost\ncertificate — some do (after a manual \"proceed anyway\" warning, since they open the URL as\na normal page), others silently reject it because their background connection check doesn't\ntrust locally-generated certs and gives no user-facing error. If adding the connector spins\nand fails with no message, that's very likely what's happening, and it's a limitation of\nthat client's trust handling, not of this server. The reliable, zero-friction way to use\nthis server today is the stdio mode above (Claude Code CLI / Claude Desktop's local server\nconfig) — reach for `--http` only if your client specifically requires a URL.\n\nThe server process must stay running for the connector to work — start it in its own\nterminal window before adding the connector, and leave that window open.\n\n## Tool reference (41 tools)\n\n| Group | Tools |\n| --- | --- |\n| Project | `set_project`, `get_project_info` |\n| Database | `list_records`, `get_record`, `update_record`, `create_record`, `get_system`, `update_system`, `set_switch_name`, `set_variable_name` |\n| Skill helpers | `create_damage_skill`, `create_healing_skill`, `create_buff_skill`, `create_state_skill` |\n| Search | `search_records`, `search_map_events` |\n| Maps & events | `list_maps`, `get_map`, `create_map`, `update_map`, `get_event`, `update_event`, `create_event`, `delete_event`, `add_event_command`, `add_dialogue`, `event_command_reference` |\n| Plugins | `list_plugins`, `configure_plugin`, `add_plugin`, `remove_plugin`, `create_plugin`, `read_plugin`, `write_plugin` |\n| Playtest | `playtest_start`, `playtest_status`, `playtest_log`, `playtest_stop` |\n| Safety | `list_backups`, `restore_backup`, `validate_project` |\n\nEvery tool description is written for AI consumption: parameter semantics, RPG Maker quirks\n(target scopes, command codes, 1-indexed arrays), and pointers to related tools are all in\nthe schema, so assistants can use the server without external documentation.\n\n## Backups\n\nThe first time a session modifies any file, the original is copied to\n`<project>/.mcp-backups/<session-timestamp>/` preserving its relative path. Up to 10\nsessions are kept. `list_backups` shows what's available; `restore_backup` restores one\nfile or a whole session — and backs up the current state first, so restores are undoable.\n\nAdd `.mcp-backups/` to your game project's `.gitignore` if the game is under version control.\n\n## Important notes\n\n- **Close the RPG Maker MV editor (or don't save from it) while the server edits files.**\n  The editor keeps the whole database in memory and overwrites the JSON files on save,\n  discarding external changes. Reopen the project in the editor to see edits made here.\n- Database arrays in MV are 1-indexed with `null` at index 0; the tools handle this\n  automatically, and ids always match array positions.\n- MZ projects (`.rmmzproject`) are accepted too — the data format is nearly identical —\n  but only MV is regularly tested.\n- Tile data editing is intentionally unsupported (`create_map` makes blank maps;\n  `update_map` refuses to touch `data`). Paint tiles in the editor.\n- NW.js playtest auto-detects Steam and KADOKAWA install paths, the project's own\n  `Game.exe`, and the `RPGMAKER_MV_NWJS` environment variable, in that order.\n- In browser playtest mode, console output stays in the browser devtools — use NW.js mode\n  when you need `playtest_log`.\n\n## Building from source\n\nFor contributors or if you prefer to build locally:\n\n```sh\ngit clone https://github.com/Xerolo44/RPG-Maker-MV-MCP.git\ncd RPG-Maker-MV-MCP\nnpm install\nnpm run build\n```\n\nThen use the local build with Claude Code:\n\n```sh\nclaude mcp add rpgmaker-mv -- node \"$(pwd)/dist/index.js\" --project \"/path/to/YourGame\"\n```\n\n## Development\n\n```sh\nnpm run build   # compile TypeScript to dist/\nnpm run smoke   # end-to-end test: real stdio client against a generated MV project\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for project layout and guidelines,\n[CHANGELOG.md](CHANGELOG.md) for release history, and [SECURITY.md](SECURITY.md) for the\ntool's trust model (it has full file-system access — read this before exposing `--http`\nmode beyond your own machine).\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 8378,
  "sha": "f49ae8cd6ef2317d7d10df894cf36f2ba47250ff8c652d930152b4c82741d0b6",
  "repo_slug": "xerolo44/rpg-maker-mv-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_xerolo44_rpgmaker_mv_mcp_64bce6d2/readme"
}