接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y [email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add rpgmaker-mv-mcp -- npx -y rpgmaker-mv-mcp@5.21.0在終端機中執行。
{ "mcpServers": { "rpgmaker-mv-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
RPG Maker MV Ultimate — AI copilot (MCP) for RPG Maker MV: generate maps, edit the database and events, and understand your project — validate broken references, explain why an event never fires, critique maps, and search names and dialogue offline.
30-second silent workflow: a visual replay of verified MCP calls and a real MV 1.6.1 playtest. Inspect the evidence.
A Model Context Protocol server that lets an AI agent inspect and edit a real RPG Maker MV project on disk through 18 consolidated tools. Find broken references and switch conditions, build events with MV-compatible commands, and run repeatable playtests. Generated data still needs validation in your game's tilesets and plugins.
It does three things that are usually missing:
Install Node.js 20.19.0 or newer, and close the MV editor before asking the agent to edit project files. Start with a copy of your project.
For containers and directory hosting, see Docker and Glama build configuration.
Windows x64 MCPB bundle: download v5.21.0 for a compatible MCPB client. See bundle requirements and verification. The npm setup below works across supported operating systems.
Check the environment before adding the server (PowerShell on Windows):
npx.cmd -y rpgmaker-mv-mcp --doctor "C:/path/to/your/RPGMakerMV/project"
coreReady: true means Node and System data checks pass. headlessReady: true additionally means Playwright and Chromium are available. The check does not start a browser or certify assets/plugins. Bridge warnings do not block offline queries. Missing Chromium: run npx.cmd playwright install chromium-headless-shell, or set RPGMAKER_MCP_CHROMIUM to your Chrome executable.
1 — Add it to your MCP client. No clone needed; the package ships an executable.
{
"mcpServers": {
"rpgmaker-mv": {
"command": "npx",
"args": ["-y", "rpgmaker-mv-mcp"],
"env": {
"RPGMAKER_PROJECT_PATH": "C:/path/to/your/RPGMakerMV/project"
}
}
}
}
# Claude Code, user scope
claude mcp add rpgmaker --scope user \
--env RPGMAKER_PROJECT_PATH="C:/path/to/project" \
-- npx -y rpgmaker-mv-mcp
# From source
git clone https://github.com/DiegoLopez0208/RpgMakerMVUltimate-MCP
cd RpgMakerMVUltimate-MCP
npm install && npm run build
RPGMAKER_PROJECT_PATH=/path/to/your/project npm start
MCP clients load tool definitions once at startup, so restart the client after adding or upgrading the server.
2 — Point it at a project. RPGMAKER_PROJECT_PATH is the folder containing data/, js/ and index.html. The server starts without it; call set_project_path at runtime instead if you prefer.
3 — Let the agent look around first.
get_project_context { detail: "full" } → what exists, with real IDs
analyze_project { view: "overview" } → health, counts, unreachable maps
Works with Claude Desktop, Claude Code, opencode, and any MCP-compatible client.
For Codex CLI, use codex mcp add rpgmaker --env RPGMAKER_PROJECT_PATH=C:/path/to/project -- npx -y rpgmaker-mv-mcp. In Windows clients that cannot launch npx, use the command cmd with arguments ["/c", "npx", "-y", "rpgmaker-mv-mcp"]. Restart the client, then try the three first-result recipes.
flowchart LR
A["🤖 Agent"] -->|"generate_map · manage_map_event"| B["📁 Project on disk"]
B -->|"validate · balance · metrics"| A
B -->|"playtest"| C["🎮 Running game"]
C -->|"exceptions · position · screenshots"| A
A -->|"reload_map"| C
The bottom half of that loop is what the bridge adds. Before it, the agent wrote files and hoped.
Two paths, both behind generate_map. Pick by whether your project uses RTP art.
{ "mode": "procedural", "theme": "town", "name": "Riverbend", "width": 40, "height": 30 }
Themes with a matching template — town, village, dungeon, interior, castle, world and more — clone a real map instead of painting tile noise. Themes without one (beach, swamp, desert…) fall back to Perlin terrain, BSP dungeons and cellular caves. Combat themes auto-wire random encounters from your existing troops; town and village auto-create enterable house interiors with two-way warps.
Themes ·
foresttownvillagecastledungeoncavebeachdesertswampruinsinteriorsnowharborvolcanosewerfortressmagic_forestmagic_interiorspace_interiorspace_exteriorworld
Other modes: blank (empty canvas), themed (simple layout), template (one specific bundled map), batch (many at once), duplicate (copy an existing map).
The bundled templates are raw MV map JSON, so their tile IDs only mean anything on RTP sheets. Change the tileset and the map turns to noise. semantic keeps the layout abstract until the last moment:
manage_system { action: "mine_templates" } # learn from THIS project
generate_map { mode: "semantic", tilesetId: 5, rooms: 6, seed: 42 }
.mcp-cache/.markers naming the cell of every mission role, which is where to put events with manage_map_event.templateId (e.g. "mined-3") to re-materialise one of your own maps onto a different tileset.playtest on its own is fire-and-forget: the game opens and nothing comes back. The bridge closes the loop.
manage_system { action: "install_bridge_plugin" } # once per project
manage_system { action: "bridge_start" } # opens ws://127.0.0.1:32123
manage_system { action: "playtest" } # the game connects on its own
manage_system { action: "bridge_telemetry", types: ["exception", "log"] }
sequenceDiagram
participant A as 🤖 Agent
participant S as 🖥️ MCP server
participant G as 🎮 Game (nwjs)
A->>S: edit_map
S->>S: atomic write to Map002.json
A->>S: bridge_command reload_map
S->>G: reload_map
G->>G: reserveTransfer + _needsMapReload
G-->>S: reload_complete
A->>S: take_screenshot
S->>G: capture_screenshot
G-->>S: PNG in base64
S-->>A: path for analyze_image
A->>S: record_video start / stop
S->>G: MediaRecorder on the game canvas
G-->>S: WebM in base64
S-->>A: path for video evidence
console.error/warn, scene changes, player position, which event command is executing (so a hung event can be pinpointed), FPS and heap. Frames are consumed as you read them unless you pass peek.reload_map re-reads the current MapXXX.json and rebuilds the scene without losing party state: it reserves a transfer to the player's own position with _needsMapReload, the engine's own reload seam, rather than rebuilding Spriteset_Map by hand. reload_database re-reads one data file; System.json and Tilesets.json need a fresh playtest and are refused with an explanation.take_screenshot { name: "collision-proof" } captures the live playtest through the MCP plugin, saves a timestamped PNG under .mcp-cache/screenshots/, and returns its path for inspection or QA evidence. No shell screenshot command is involved. manage_system { action: "bridge_screenshot" } remains as a compatibility alias.record_video { action: "start", name: "npc-dialogue" } begins a silent WebM capture of the live game canvas; record_video { action: "stop" } saves it under .mcp-cache/recordings/ and returns its path. Agents can stage repeatable scenes with the allowlisted interact command and fixed-button press_button input—there is still no arbitrary script or eval command.🔒 Security
The plugin returns before anything else runs unless the game is under NW.js and was launched with a
testargument. A deployed build a player double-clicks never reaches the socket code, or evenrequire('fs').It checks every argument rather than only
argv[0]the wayUtils.isOptionValiddoes, becauseplaytestpasses the project path first. So a deployed build deliberately launched with a literaltestargument would get past the guard — and then find no handshake file, and never connect.The server binds
127.0.0.1only, refuses any upgrade carrying a browserOrigin(cross-site WebSocket hijacking), and requires the session token from.mcp-bridge.json— compared in constant time — within 5 seconds or the connection is dropped.The command surface is a fixed allowlist with no
evalprimitive.
analyze_project is read-only and fully offline. It models the whole project once, so an agent can reason about a game it did not build.
Broken transfers, missing map files, dangling common-event/item/troop references, duplicate IDs, named-but-unused switches and variables, a bad starting position, unreachable maps — and actor names written into dialogue as \N[id] that do not resolve.
That last one is worth its own sentence: the engine resolves \N[id] at draw time, not from any structural parameter, so a bad id passes every other check and the editor shows nothing wrong. The line just renders in-game with a hole where the name should be, and a player finds it before you do.
expected (interior / dungeon / exterior).A skill dealing 400 damage is fine in a game where everything does, and broken in one where nothing else breaks 60. So each entry is scored on a power metric and compared against the others in its category: damage per MP for skills, gold per point of ATK+MAT for weapons, gold per DEF+MDF for armors, HP per EXP for enemies.
The comparison is leave-one-out — an entry is judged against statistics it had no hand in creating. Included in its own numbers, a badly broken entry drags the mean toward itself until it stops looking unusual at all.
Damage formulas are parsed, never executed (tokenise → shunting-yard → evaluate). One that cannot be read statically is listed under unreadableFormulas rather than scored as zero damage, which would pull every average down and hide the very outliers you were looking for.
Narrow with category, loosen or tighten with thresholdSd (default 2).
Search returns searchMode: "lexical", complete, indexedFiles, skippedFiles and warnings. complete: false means some data could not be read; it does not mean the game contains no matching content. An empty result includes noResultsReason. Use a name or phrase actually present in the project: herrero does not translate into Blacksmith. Unicode names, including Japanese, are supported. A database query for an absent ID can return null; inspect it before using that ID.
Index, overview, validation, graph, usage, explain and refactor also report incomplete input. Unreadable files appear as validation errors.
query_map { view: "ascii", mapId } — render a map as a character grid with event markers. The cheapest way to see a layout and pick coordinates.query_map { view: "validate", mapId } — lint one map for invalid tile IDs, broken transfers and missing event terminators.The server exposes 18 consolidated tools. The legacy aliases are optional.
The 101 fine-grained v4 tool names still work as call aliases. Set RPGMV_LEGACY_TOOLS=1 to advertise them too.
For composed event logic, use build_event_commands followed by
insert_event_commands with dryRun:true. The preview includes the exact old and
proposed command lists. See Event command authoring for
the supported kinds, nesting rules, MV-specific differences, and verification.
.mcp-backups/ (last N, RPGMV_BACKUP_KEEP, default 10). A backup failure aborts replacement. Writes use unique temporary files and exclusive per-file locks; changes detected since a data read are refused. Close the editor: it does not honor MCP locks, and multi-file operations are not transactions.dryRun: true to any mutating tool to see exactly what it would write, without touching disk.⚠️ Close the RPG Maker editor while an agent is working. The editor holds the project in memory and will overwrite changes when it saves.
analyze_image { mode: "ai" } sends a project image (tileset, sprite, screenshot, battler) to any OpenAI-compatible endpoint. Nothing is sent anywhere unless you configure it; the grid and colors modes and every other tool work fully offline.
# OpenAI
VISION_API_URL=https://api.openai.com VISION_API_KEY=sk-... VISION_MODEL=gpt-4o npm start
# Ollama (local, no key)
VISION_API_URL=http://localhost:11434 VISION_MODEL=llava npm start
Works with OpenAI, Ollama, LocalAI, NVIDIA NIM, vLLM, LiteLLM, or any OpenAI-compatible proxy.
A portable Agent Skill teaches any model the crash-free workflow — build maps with generate_map, add content with manage_map_event presets, never hand-paint tiles or guess IDs. It lives at skill/rpgmaker-mv-mcp/SKILL.md.
# Claude Code / Claude.ai
npx degit DiegoLopez0208/RpgMakerMVUltimate-MCP/skill/rpgmaker-mv-mcp ~/.claude/skills/rpgmaker-mv-mcp
# opencode
npx degit DiegoLopez0208/RpgMakerMVUltimate-MCP/skill/rpgmaker-mv-mcp ~/.opencode/skills/rpgmaker-mv-mcp
Also listed in awesome-claude-skills.
mode: "semantic" currently generates dungeon-shaped missions. Town and open-world mission grammars are next, as is using the mined adjacency counts to decorate rather than only to describe.balance compares like with like inside a category, so a boss will legitimately look like an outlier next to random encounters. Read the flag, not the verdict.npm install
npm run build # tsc compile (+ copies knowledge/ into dist/)
npm test # vitest
npm run typecheck
npm run dev # tsx watch mode
Actively developed, and feedback is very welcome — bug reports, weird maps, missing tools, ideas. Open a GitHub Issue with what you asked the agent to do and what you got; an exported map JSON or a screenshot helps a lot.
MIT · Built for RPG Maker MV
RPG Maker MV Ultimate — AI copilot (MCP) for RPG Maker MV: generate maps, edit the database and events, and understand your project — validate broken references, explain why an event never fires, crit
{ "mcpServers": { "rpgmaker-mv-mcp": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}總覽
RPG Maker MV Ultimate — AI copilot (MCP) for RPG Maker MV: generate maps, edit the database and events, and understand your project — validate broken references, explain why an event never fires, critique maps, and search names and dialogue offline.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Rpgmaker Mv 透過 stdio 在本機執行。
上次檢查時間:2026-11-16。 RPG Maker MV Ultimate — AI copilot (MCP) for RPG Maker MV: generate maps, edit the database and events, and understand your project — validate broken references, explain why an event never fires, critique maps, and search names and dialogue offline.