RPG Maker MZ/MV 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/MV MCP Server Create a 'Fireball' skill that deals 4x magic damage to one enemy"
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/MV/MV MCP Server
A Model Context Protocol (MCP) server for RPG Maker MZ/MV & MV integration. This server provides comprehensive tools for managing game data, maps, events, skills, and system settings through the MCP protocol.
Features
Actor Management: Create, read, update, and search actors
Item/Equipment Management: Manage items, weapons, armors, and skills
Skill Creation: Create custom skills with natural language (NEW!)
Damage skills, healing skills, buffs, debuffs, status effects
Simplified helpers for common skill types
Full customization support
Map Management: Access and modify map data, tiles, and properties
Event Management: Create, update, and manage map events and commands
System Configuration: Update game settings, variables, switches, and vocabulary
Type Safety: Full TypeScript support with comprehensive type definitions
Error Handling: Robust error handling and validation
Related MCP server: RPG Maker MV Copilot MCP
Installation
npm install
npm run buildConfiguration
Set the RPG Maker MZ/MV project path as an environment variable:
# Windows
set RPGMAKER_PROJECT_PATH=C:\path\to\your\rpgmaker\project
# macOS/Linux
export RPGMAKER_PROJECT_PATH=/path/to/your/rpgmaker/projectUsage
Running the Server
npm startOr directly:
node dist/index.jsConfiguring in Claude Desktop
Add to your Claude Desktop configuration file:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"rpgmaker-mz": {
"command": "node",
"args": ["C:/path/to/rpgmaker-mz-mcp/dist/index.js"],
"env": {
"RPGMAKER_PROJECT_PATH": "C:/path/to/your/rpgmaker/project"
}
}
}
}Available Tools
Actor Tools
get_actors- Get all actors from the projectget_actor- Get a specific actor by IDupdate_actor- Update an actor's propertiescreate_actor- Create a new actorsearch_actors- Search actors by name or nickname
Item Tools
get_items- Get all items from the projectget_weapons- Get all weapons from the projectget_armors- Get all armors from the projectget_skills- Get all skills from the projectupdate_item- Update an item's propertiessearch_items- Search items by name or description
Skill Tools (NEW!)
get_skill- Get a specific skill by IDcreate_skill- Create a custom skill with full controlcreate_damage_skill- Create a damage-dealing skill (simplified)create_healing_skill- Create a healing skill (simplified)create_buff_skill- Create a buff skill (simplified)create_state_skill- Create a state-inflicting skill (simplified)update_skill- Update a skill's propertiessearch_skills- Search skills by name or description
Map Tools
get_map- Get map data by IDget_map_infos- Get information about all mapsget_map_events- Get all events from a specific mapget_map_event- Get a specific event from a mapupdate_map_event- Update a map event's propertiescreate_map_event- Create a new event on a mapsearch_map_events- Search events on a map by nameadd_event_command- Add a command to an event page
System Tools
get_system- Get system dataget_variables- Get all game variable namesset_variable_name- Set a variable nameget_switches- Get all game switch namesset_switch_name- Set a switch nameget_game_title- Get the game titleupdate_game_title- Update the game titleupdate_starting_position- Update the game starting position
Example Usage
Once configured, you can use Claude to interact with your RPG Maker MZ/MV project:
Example 1: Get All Actors
Show me all actors in my RPG Maker MZ/MV projectClaude will use the get_actors tool to retrieve and display all actors.
Example 2: Update an Actor
Update actor 1's name to "Hero" and initial level to 5Claude will use the update_actor tool with the appropriate parameters.
Example 3: Create a New Item
Create a new item called "Health Potion" that restores 50 HPClaude will help you create the item with the proper structure.
Example 4: Search Map Events
Find all events on map 1 that contain "treasure" in their nameClaude will use the search_map_events tool to find matching events.
Example 5: Update Game Settings
Change the game title to "My Epic Adventure"Claude will use the update_game_title tool to update the system data.
Example 6: Create a Custom Skill
Create a fire magic skill called "Fireball" that costs 15 MP,
targets a single enemy, and deals "a.mat * 4 - b.mdf * 2" damageClaude will use the create_damage_skill tool to create the skill.
Example 7: Create a Healing Skill
Create a group healing spell called "Mass Heal" that costs 30 MP,
targets all allies, and heals "a.mat * 3 + 100" HPClaude will use the create_healing_skill tool to create the healing skill.
Data Structure Reference
Actor Structure
{
id: number;
name: string;
nickname: string;
profile: string;
classId: number;
initialLevel: number;
maxLevel: number;
characterName: string;
characterIndex: number;
faceName: string;
faceIndex: number;
battlerName: string;
traits: Trait[];
equips: number[];
note: string;
}Map Event Structure
{
id: number;
name: string;
note: string;
pages: EventPage[];
x: number;
y: number;
}Event Command Structure
{
code: number; // Command code (see RPG Maker MZ/MV documentation)
indent: number; // Indentation level
parameters: any[]; // Command parameters
}Common Event Command Codes
101- Show Text102- Show Choices111- Conditional Branch112- Loop113- Break Loop121- Control Switches122- Control Variables125- Change Gold126- Change Items201- Transfer Player356- Plugin Command
For a complete list, refer to the RPG Maker MZ/MV documentation.
Development
Building
npm run buildWatch Mode
npm run devProject Structure
rpgmaker-mz-mcp/
├── src/
│ ├── index.ts # Main MCP server
│ ├── tools/
│ │ ├── actorTools.ts # Actor management functions
│ │ ├── itemTools.ts # Item/equipment management
│ │ ├── mapTools.ts # Map and event management
│ │ └── systemTools.ts # System settings management
│ └── utils/
│ ├── fileHandler.ts # File I/O utilities
│ └── types.ts # TypeScript type definitions
├── dist/ # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.mdSafety and Best Practices
Backup Your Project: Always backup your RPG Maker MZ/MV project before making changes
Close RPG Maker MZ/MV Editor: Close the RPG Maker MZ/MV editor when using this server to avoid conflicts
Validate Changes: Test your game after making changes to ensure everything works correctly
Version Control: Use git or another version control system for your project
Limitations
This server modifies JSON files directly. Make sure the RPG Maker MZ/MV editor is closed when using it
Some advanced features may require manual editing in the RPG Maker MZ/MV editor
Plugin-specific data structures may not be fully supported
Troubleshooting
"Invalid RPG Maker MZ/MV project path"
Make sure the RPGMAKER_PROJECT_PATH environment variable points to a valid RPG Maker MZ or MV project directory containing:
game.rmmzprojectfile (MZ) orGame.rpgprojectfile (MV)data/directory withSystem.json
Changes Not Appearing
Make sure the RPG Maker MZ/MV editor is closed
Verify the project path is correct
Check that the JSON files have write permissions
Tool Not Found
Restart Claude Desktop after updating the configuration file.
Contributing
Contributions are welcome! Please ensure:
Code follows TypeScript best practices
All functions include proper error handling
Type definitions are updated for new features
Documentation is updated accordingly
License
MIT
Resources
Support
For issues and feature requests, please open an issue on the project repository.
Available Tools
37 toolsadd_event_commandC
Add a command to an event page
Inputs: mapId (required), eventId (required), pageIndex (required), command (required), +1 more.
create_actorD
Create a new actor
Inputs: name (required), nickname, profile, classId, +10 more.
create_buff_skillC
Create a buff skill (simplified)
Inputs: name (required), buffType (required), turns (required), mpCost (required), +2 more.
create_damage_skillC
Create a damage-dealing skill (simplified)
Inputs: name (required), damageFormula (required), mpCost (required), scope (required), +2 more.
create_healing_skillC
Create a healing skill (simplified)
Inputs: name (required), healFormula (required), mpCost (required), scope (required), +1 more.
create_mapB
Create a new map with specified dimensions and properties. Returns the new map ID and map data.
Inputs: name, width, height, displayName, +6 more.
create_map_eventD
Create a new event on a map
Inputs: mapId (required), name (required), x (required), y (required), +2 more.
create_skillC
Create a new skill with custom properties
Inputs: name (required), description, iconIndex, mpCost, +7 more.
create_state_skillC
Create a state-inflicting skill (poison, sleep, etc.)
Inputs: name (required), stateId (required), chance (required), mpCost (required), +2 more.
get_actorC
Get a specific actor by ID
Inputs: actorId (required).
get_actorsB
Get all actors from the RPG Maker MZ/MV project
Inputs: no named parameters.
get_armorsB
Get all armors from the project
Inputs: no named parameters.
get_game_titleC
Get the game title
Inputs: no named parameters.
get_itemsB
Get all items from the project
Inputs: no named parameters.
get_mapC
Get map data by ID
Inputs: mapId (required).
get_map_eventC
Get a specific event from a map
Inputs: mapId (required), eventId (required).
get_map_eventsA
Get all events from a specific map
Inputs: mapId (required).
get_map_infosB
Get information about all maps
Inputs: no named parameters.
get_skillA
Get a specific skill by ID
Inputs: skillId (required).
get_skillsA
Get all skills from the project
Inputs: no named parameters.
get_switchesB
Get all game switch names
Inputs: no named parameters.
get_systemC
Get system data
Inputs: no named parameters.
get_variablesA
Get all game variable names
Inputs: no named parameters.
get_weaponsB
Get all weapons from the project
Inputs: no named parameters.
paint_mapA
Paint tiles on a map using batch operations (fill rectangles or draw outlines). Efficient for creating terrain, roads, walls, and decorations in one call. Reads/writes map data only once regardless of operation count.
Inputs: mapId (required), operations (required).
search_actorsB
Search actors by name or nickname
Inputs: searchTerm (required).
search_itemsC
Search items by name or description
Inputs: searchTerm (required).
search_map_eventsB
Search events on a map by name
Inputs: mapId (required), searchTerm (required).
search_skillsB
Search skills by name or description
Inputs: searchTerm (required).
set_switch_nameC
Set a switch name
Inputs: switchId (required), name (required).
set_variable_nameD
Set a variable name
Inputs: variableId (required), name (required).
update_actorC
Update an actor's properties
Inputs: actorId (required), updates (required).
update_game_titleC
Update the game title
Inputs: title (required).
update_itemD
Update an item's properties
Inputs: itemId (required), updates (required).
update_map_eventD
Update a map event's properties
Inputs: mapId (required), eventId (required), updates (required).
update_skillC
Update a skill's properties
Inputs: skillId (required), updates (required).
update_starting_positionD
Update the game starting position
Inputs: mapId (required), x (required), y (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 37 tools
The five different skill creation tools (create_skill plus four specialized variants) create significant overlap and potential confusion about which to use. While other tools are well-differentiated by resource type and action, the skill creation redundancy and the similarity between 'create_map_event' and 'add_event_command' (which targets event pages, not events) could cause misselection.
Tools follow a consistent snake_case convention with clear verb_noun patterns. Verbs are well-chosen and semantically distinct (create vs add vs update vs set vs paint). The only minor issue is the mix of singular and plural nouns (get_actor vs get_actors), though this follows a predictable pattern for list vs single-item retrieval.
With 37 tools, the surface is quite heavy and pushes beyond the ideal range for an MCP server. While RPG Maker is a complex domain requiring coverage of actors, skills, maps, and events, the count is inflated by redundant skill creation shortcuts and very granular operations. The breadth risks overwhelming agent context windows.
The surface covers major game elements (actors, skills, maps, events) with reasonable CRUD operations, but has notable gaps: items lack a create operation despite having update, armors and weapons are read-only, and there's no apparent delete functionality for any resource. Missing game systems like enemies, troops, and classes limit full game authoring capability.
Maintenance
Related MCP Connectors
MCP server for AI dialogue using various LLM models via AceDataCloud
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
Official remote MCP server for Archivist AI TTRPG campaign memory: characters, sessions, and more.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables AI models to develop and automate RPG Maker MZ projects by creating maps, events, and plugins through natural language commands. It provides comprehensive tools for database management, asset integrity checks, and direct map tile manipulation.2813 npm1ISC
- AlicenseAqualityBmaintenanceMCP tools to debug events, edit maps, and playtest RPG Maker MV projects with AI18252 npm32MIT
- AlicenseBqualityDmaintenanceA stable, well-tested MCP server that lets AI assistants create and edit RPG Maker MZ projects through natural language.23173 npm8GPL 3.0
- AlicenseCqualityDmaintenanceProvides tools for managing RPG Maker MZ game data, maps, events, and system settings through natural language, enabling AI-assisted game development.3535MIT