RPG Maker MZ MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@RPG Maker MZ MCP Server Create a warrior character named Roland with high attack."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🎮 RPG Maker MZ MCP Server
A stable, well-tested Model Context Protocol server that lets AI assistants like Claude create and edit RPG Maker MZ projects through natural language.
Why another one? Existing RPG Maker MZ MCP servers on GitHub suffer from critical issues — stdout pollution breaking the MCP protocol, wrong file extensions, no atomic writes, no tests, and outdated SDKs. This project was built from scratch to fix all of them.
✨ Features
Feature | This Project | Others |
Atomic file writes ( | ✅ | ❌ |
Auto | ✅ | ❌ |
Zod schema validation on reads | ✅ | ❌ |
stderr-only logging (no stdout pollution) | ✅ | ❌ |
Correct | ✅ | ❌ |
Generic | ✅ | ❌ |
Unit & integration tests (42 tests) | ✅ | ❌ |
MCP SDK v1.26+ | ✅ | ❌ |
Event editing with human-readable commands | ✅ | Partial |
AI scenario generation tools | ✅ | ❌ |
Related MCP server: godot-mcp-pilot
🛠 Available Tools (23 total)
Project Management (4)
Tool | Description |
| Load an existing RPG Maker MZ project |
| Create a new project with all default data files |
| Get project stats (maps, actors, items, etc.) |
| List images and audio files in the project |
Database CRUD (6 tools × 8 entity types)
Unified tools that work with actors, classes, skills, items, weapons, armors, enemies, and states:
Tool | Description |
| List all entities of a given type |
| Get entity details by ID |
| Create a new entity with Zod validation |
| Partial update of an existing entity |
| Delete an entity (protects system defaults) |
| Search by keyword across name/description |
Map Management (5)
Tool | Description |
| List all maps with hierarchy |
| Create a new map with size, tileset, BGM |
| Get map details including events |
| Update map properties |
| Delete a map |
Event Editing (5)
Tool | Description |
| List events on a map |
| Create a new event at a position |
| Update event properties |
| Add commands using human-readable format |
| Delete an event |
40+ supported command types including show_text, show_choices, transfer_player, control_switches, play_bgm, battle_processing, shop_processing, and more.
AI Scenario Generation (3)
Tool | Description |
| Generate a game scenario outline from a theme |
| Generate NPC dialogue as event commands |
| Design a quest with objectives and rewards |
These tools leverage the AI's own capabilities — no external API calls needed.
📦 Installation
# Clone the repository
git clone https://github.com/a951753abc/rpgmaker-mz-mcp.git
cd rpgmaker-mz-mcp
# Install dependencies
npm install
# Build
npm run build
# Verify (42 tests should pass)
npm test⚙️ Configuration
Claude Code (CLI)
Create a .mcp.json file in your project directory:
{
"mcpServers": {
"rpgmaker-mz": {
"command": "node",
"args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]
}
}
}Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"rpgmaker-mz": {
"command": "node",
"args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]
}
}
}💬 Usage Examples
Once the MCP server is connected, talk to Claude naturally:
You: Load my RPG Maker MZ project at /Users/me/Games/MyRPG
You: Create a warrior character named "Roland" with high attack
You: Create a 20x15 village map called "Oakwood Village" with Town1 BGM
You: Add an NPC shopkeeper on map 2 at position (8, 6)
You: Add dialogue to the shopkeeper: "Welcome! Take a look at my wares."
You: Generate a quest about rescuing a kidnapped princess
You: Create a healing potion item that restores 200 HP🏗 Architecture
src/
├── index.ts # MCP Server entry point (stdio transport)
├── logger.ts # stderr-only logger
├── core/
│ ├── file-handler.ts # Atomic writes + backups + Zod validation
│ ├── project-manager.ts # Project loading / validation
│ ├── database-manager.ts # Generic CRUD for all entity types
│ └── version-sync.ts # System.json versionId auto-sync
├── schemas/
│ ├── database.ts # Zod schemas for 8 entity types
│ ├── map.ts # Map & audio schemas
│ ├── event.ts # Event & command schemas + converter
│ └── system.ts # System.json schema
├── tools/
│ ├── project-tools.ts # 4 project management tools
│ ├── database-tools.ts # 6 database CRUD tools
│ ├── map-tools.ts # 5 map management tools
│ ├── event-tools.ts # 5 event editing tools
│ └── scenario-tools.ts # 3 AI scenario tools
└── templates/
└── defaults.ts # RPG Maker MZ default data templatesKey Design Decisions
Atomic writes: Write to
.tmp→fs.rename()to target. Rename is atomic on the same filesystem, preventing data corruption from partial writes.Auto backup: Every write creates a
.bakfile before overwriting, enabling easy recovery.Zod validation: All JSON reads are validated through Zod schemas instead of unsafe
as Ttype assertions.Generic DatabaseManager<T>: One class handles CRUD for all 8 entity types, eliminating code duplication.
stderr-only logging: MCP uses stdout for JSON-RPC. Any
console.logwould corrupt the protocol. We useconsole.errorexclusively.Version sync: Every data file modification bumps
System.jsonversionId, forcing RPG Maker MZ editor to reload.
🧪 Development
# Run tests
npm test
# Watch mode
npm run test:watch
# Build
npm run build
# Dev mode (auto-rebuild on changes)
npm run devRuntime Dependencies (minimal)
Package | Purpose |
| MCP protocol implementation |
| Schema validation |
That's it. Just 2 runtime dependencies.
📄 License
This project is licensed under the GNU General Public License v3.0.
You are free to use, modify, and distribute this software, provided that derivative works are also distributed under the same license.
繁體中文
簡介
一個穩定、經過完整測試的 Model Context Protocol 伺服器,讓 Claude 等 AI 助手能透過自然語言建立和編輯 RPG Maker MZ 專案。
為什麼要重新開發? GitHub 上現有的 RPG Maker MZ MCP Server 都有嚴重問題 — stdout 污染導致 MCP 協議損壞、副檔名錯誤、沒有原子寫入、沒有測試、SDK 過時。本專案從頭開發,解決了所有已知問題。
特色
原子寫入:先寫入
.tmp暫存檔,再用fs.rename()覆蓋目標,防止寫入中斷導致資料損壞自動備份:每次寫入前自動建立
.bak備份檔Zod 驗證:讀取 JSON 時透過 Zod schema 驗證,取代不安全的
as T型別斷言泛型資料庫管理器:一個
DatabaseManager<T>處理所有 8 種實體的 CRUD,消除重複程式碼stderr 日誌:MCP 使用 stdout 進行 JSON-RPC 通訊,任何
console.log都會破壞協議。本專案只用console.error版本同步:每次修改資料檔案後自動更新
System.json的versionId,強制 RPG Maker MZ 編輯器重新載入
可用工具(共 23 個)
類別 | 工具數 | 說明 |
專案管理 | 4 | 載入 / 建立 / 查詢專案資訊 / 列出素材資源 |
資料庫 CRUD | 6 | 列出 / 取得 / 新增 / 更新 / 刪除 / 搜尋(支援角色、職業、技能、道具、武器、防具、敵人、狀態) |
地圖管理 | 5 | 列出 / 建立 / 查看 / 更新 / 刪除地圖 |
事件編輯 | 5 | 列出 / 建立 / 更新 / 新增指令 / 刪除事件(支援 40+ 種人類可讀指令格式) |
AI 劇情生成 | 3 | 生成遊戲劇情大綱 / NPC 對話 / 任務設計 |
使用範例
連接 MCP Server 後,用自然語言跟 Claude 對話即可:
你:載入我的 RPG Maker MZ 專案,路徑是 /Users/me/Games/MyRPG
你:建立一個戰士角色,名字叫「羅蘭」,攻擊力要高
你:建立一張 20x15 的村莊地圖,叫做「橡木村」,背景音樂用 Town1
你:在地圖 2 的座標 (8, 6) 放一個 NPC 商人
你:幫商人加一段對話:「歡迎光臨!請看看我的商品。」
你:幫我設計一個拯救被綁架公主的任務
你:建立一個回復 200 HP 的治療藥水安裝與設定
git clone https://github.com/a951753abc/rpgmaker-mz-mcp.git
cd rpgmaker-mz-mcp
npm install
npm run build
npm test # 42 個測試應全部通過在你的專案目錄建立 .mcp.json:
{
"mcpServers": {
"rpgmaker-mz": {
"command": "node",
"args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]
}
}
}日本語
概要
安定性が高く、十分にテスト済みの Model Context Protocol サーバーです。Claude などの AI アシスタントが自然言語で RPG Maker MZ(RPGツクールMZ)のプロジェクトを作成・編集できるようにします。
なぜ新しく開発したのか? GitHub 上の既存の RPG Maker MZ MCP サーバーには深刻な問題があります — stdout 汚染による MCP プロトコル破損、間違ったファイル拡張子、アトミック書き込みなし、テストなし、古い SDK。本プロジェクトはこれらすべてをゼロから解決しました。
特徴
アトミック書き込み:
.tmp一時ファイルに書き込み →fs.rename()で上書き。書き込み途中のデータ破損を防止自動バックアップ:書き込み前に自動で
.bakバックアップを作成Zod バリデーション:JSON 読み取り時に Zod スキーマで検証。安全でない
as T型アサーションを排除汎用データベースマネージャー:
DatabaseManager<T>一つで全 8 種のエンティティの CRUD を処理。コードの重複を排除stderr 専用ログ:MCP は stdout を JSON-RPC 通信に使用。
console.logはプロトコルを破壊するため、console.errorのみ使用バージョン同期:データファイル変更のたびに
System.jsonのversionIdを自動更新し、RPGツクールMZ エディタに再読み込みを強制
利用可能なツール(全 23 個)
カテゴリ | ツール数 | 説明 |
プロジェクト管理 | 4 | 読み込み / 作成 / 情報取得 / リソース一覧 |
データベース CRUD | 6 | 一覧 / 取得 / 作成 / 更新 / 削除 / 検索(アクター、職業、スキル、アイテム、武器、防具、敵キャラ、ステート対応) |
マップ管理 | 5 | 一覧 / 作成 / 詳細 / 更新 / 削除 |
イベント編集 | 5 | 一覧 / 作成 / 更新 / コマンド追加 / 削除(40以上の人間が読めるコマンド形式対応) |
AI シナリオ生成 | 3 | ゲームシナリオ概要 / NPC 会話 / クエスト設計の生成 |
使用例
MCP サーバー接続後、Claude に自然言語で話しかけるだけで操作できます:
あなた:/Users/me/Games/MyRPG にある RPGツクールMZ のプロジェクトを読み込んで
あなた:「ローランド」という名前の戦士キャラクターを作って、攻撃力を高めに
あなた:20x15 の村マップを作って、名前は「オークウッド村」、BGMは Town1 で
あなた:マップ 2 の座標 (8, 6) に NPC の商人を配置して
あなた:商人にセリフを追加して:「いらっしゃいませ!商品をご覧ください。」
あなた:さらわれた姫を救出するクエストを設計して
あなた:HP を 200 回復する回復薬を作ってインストールと設定
git clone https://github.com/a951753abc/rpgmaker-mz-mcp.git
cd rpgmaker-mz-mcp
npm install
npm run build
npm test # 42 テストがすべてパスするはずプロジェクトディレクトリに .mcp.json を作成:
{
"mcpServers": {
"rpgmaker-mz": {
"command": "node",
"args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"]
}
}
}Available Tools
23 toolsadd_event_commandsA
Add commands to an event page. Commands use human-readable format that gets converted to RPG Maker MZ codes.
Supported command types:
show_text: { type: "show_text", face: "Actor1", faceIndex: 0, text: "Hello!" }
show_choices: { type: "show_choices", choices: ["Yes", "No"] }
transfer_player: { type: "transfer_player", mapId: 1, x: 5, y: 5 }
control_switches: { type: "control_switches", startId: 1, value: 0 } (0=ON, 1=OFF)
control_variables: { type: "control_variables", startId: 1, operationType: 0, operand: 0, value: 100 }
control_self_switch: { type: "control_self_switch", key: "A", value: 0 }
conditional_branch: { type: "conditional_branch", conditionType: 0, param1: 1, param2: 0 }
common_event: { type: "common_event", eventId: 1 }
change_gold: { type: "change_gold", operation: 0, value: 100 }
change_items: { type: "change_items", itemId: 1, operation: 0, value: 1 }
play_bgm: { type: "play_bgm", name: "Town1", volume: 90 }
play_se: { type: "play_se", name: "Decision1" }
wait: { type: "wait", duration: 60 }
fadeout_screen, fadein_screen, erase_event, game_over, return_to_title
comment: { type: "comment", text: "This is a comment" }
label/jump_to_label: { type: "label", name: "start" }
And many more (change_hp, change_exp, battle_processing, shop_processing, etc.)
Inputs: mapId (required), eventId (required), commands (required), append, +1 more.
create_entityB
Create a new entity. Provide the entity data as a JSON object. Required: name. Other fields use defaults if omitted.
Inputs: data (required), entityType (required).
create_eventC
Create a new event on a map at the specified position.
Inputs: x (required), y (required), name (required), mapId (required), +4 more.
create_mapC
Create a new map.
Inputs: name (required), width, height, bgmName, +2 more.
create_projectA
Create a new RPG Maker MZ project with default data files.
Inputs: gameTitle (required), projectPath (required), rpgmakerPath.
delete_entityA
Delete an entity by ID. Cannot delete system default entities (ID 1) for actors/classes/states.
Inputs: id (required), entityType (required).
delete_eventC
Delete an event from a map.
Inputs: mapId (required), eventId (required).
delete_mapB
Delete a map. Cannot delete Map 1 (system default).
Inputs: mapId (required).
generate_dialogueA
Generate NPC dialogue for a scene. Returns event commands that can be directly used with add_event_commands.
Inputs: scene (required), npcName (required), mood, faceName, +2 more.
generate_questC
Generate a quest design with objectives, rewards, and event flow.
Inputs: questType (required), description (required), difficulty, rewardType.
generate_scenarioA
Generate a game scenario outline based on theme and genre. Returns structured suggestions that can be implemented using other tools (create_entity, create_map, create_event, etc.).
Inputs: theme (required), genre, scope.
get_entityB
Get detailed information about a specific entity by ID.
Inputs: id (required), entityType (required).
get_mapB
Get detailed information about a specific map, including its events.
Inputs: mapId (required).
get_project_infoA
Get information about the currently loaded RPG Maker MZ project.
Inputs: no named parameters.
list_entitiesC
List all entities of a given type (actors, items, weapons, etc.)
Inputs: entityType (required).
list_eventsC
List all events on a specific map.
Inputs: mapId (required).
list_mapsB
List all maps in the project with their hierarchy.
Inputs: no named parameters.
list_resourcesC
List resource files (images, audio) in the project.
Inputs: type.
load_projectA
Load an existing RPG Maker MZ project. Must be called before using other tools.
Inputs: projectPath (required).
search_entitiesC
Search entities by keyword across name and description fields.
Inputs: query (required), entityType (required).
update_entityB
Update an existing entity. Only provided fields will be changed.
Inputs: id (required), data (required), entityType (required).
update_eventC
Update event properties (name, position, note, character sprite).
Inputs: mapId (required), eventId (required), x, y, +4 more.
update_mapC
Update map properties (name, display name, BGM, note, etc.).
Inputs: mapId (required), name, note, bgmName, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools have clearly distinct purposes, cleanly separated by resource (entities, maps, events) and action (list/get/create/update/delete). The only mild overlap is among the generation tools (generate_quest, generate_scenario, generate_dialogue), which are related but target different scopes (quest vs. full scenario vs. dialogue), and add_event_commands vs. generate_dialogue which is complementary rather than conflicting.
Nearly every tool follows a strict verb_noun snake_case pattern (get_project_info, load_project, create_entity, update_map, delete_event, add_event_commands). The convention is applied uniformly across projects, resources, entities, maps, and events with no style mixing.
23 tools sits at the heavy end of the reasonable range, but the domain genuinely spans projects, resources, entities, maps, events, event commands, and content generators, so most tools earn their place. Slightly more than ideal, but not bloated or redundant.
The surface covers the full lifecycle well: project load/create/info, entity and map and event CRUD, and rich event-command authoring plus generators. Minor gaps exist (e.g. no get_event for a single event, no way to remove/edit already-added event commands, no delete_project), but agents can work around these.
Maintenance
Related MCP Connectors
An MCP server that integrates with Discord to provide AI-powered features.
MCP server for AI dialogue using various LLM models via AceDataCloud
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- AlicenseCqualityDmaintenanceA Model Context Protocol server that enables management of RPG Maker MZ and MV project data, including actors, items, maps, and events. It allows users to create, update, and search game assets through natural language integration with MCP-compatible clients.372MIT
- AlicenseAqualityDmaintenanceAn MCP server that gives AI assistants direct control over Godot 4 game development projects. It enables launching the editor, running projects, creating and editing scenes, writing GDScript, and inspecting assets through natural language commands.4414 npm4MIT
- AlicenseNot gradedqualityCmaintenanceA plugin-based MCP server that enables AI assistants to interact with external systems through custom tools, resources, and prompts.4AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceAn MCP server that enables AI agents to act as dynamic dungeon masters for text-based RPGs with dynamically generated rule systems and comprehensive game state management.15MIT