Content
# RPG Maker MZ MCP Server
A high-quality Model Context Protocol (MCP) server for RPG Maker MZ integration. This server provides comprehensive tools for managing game data, maps, events, 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
## Installation
```bash
npm install
npm run build
```
## Configuration
Set the RPG Maker MZ project path as an environment variable:
```bash
# Windows
set RPGMAKER_PROJECT_PATH=C:\path\to\your\rpgmaker\project
# macOS/Linux
export RPGMAKER_PROJECT_PATH=/path/to/your/rpgmaker/project
```
## Usage
### Running the Server
```bash
npm start
```
Or directly:
```bash
node dist/index.js
```
### Configuring 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`
```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 project
- `get_actor` - Get a specific actor by ID
- `update_actor` - Update an actor's properties
- `create_actor` - Create a new actor
- `search_actors` - Search actors by name or nickname
### Item Tools
- `get_items` - Get all items from the project
- `get_weapons` - Get all weapons from the project
- `get_armors` - Get all armors from the project
- `get_skills` - Get all skills from the project
- `update_item` - Update an item's properties
- `search_items` - Search items by name or description
### Skill Tools (NEW!)
- `get_skill` - Get a specific skill by ID
- `create_skill` - Create a custom skill with full control
- `create_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 properties
- `search_skills` - Search skills by name or description
### Map Tools
- `get_map` - Get map data by ID
- `get_map_infos` - Get information about all maps
- `get_map_events` - Get all events from a specific map
- `get_map_event` - Get a specific event from a map
- `update_map_event` - Update a map event's properties
- `create_map_event` - Create a new event on a map
- `search_map_events` - Search events on a map by name
- `add_event_command` - Add a command to an event page
### System Tools
- `get_system` - Get system data
- `get_variables` - Get all game variable names
- `set_variable_name` - Set a variable name
- `get_switches` - Get all game switch names
- `set_switch_name` - Set a switch name
- `get_game_title` - Get the game title
- `update_game_title` - Update the game title
- `update_starting_position` - Update the game starting position
## Example Usage
Once configured, you can use Claude to interact with your RPG Maker MZ project:
### Example 1: Get All Actors
```
Show me all actors in my RPG Maker MZ project
```
Claude 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 5
```
Claude 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 HP
```
Claude 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 name
```
Claude 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" damage
```
Claude 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" HP
```
Claude will use the `create_healing_skill` tool to create the healing skill.
## Data Structure Reference
### Actor Structure
```typescript
{
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
```typescript
{
id: number;
name: string;
note: string;
pages: EventPage[];
x: number;
y: number;
}
```
### Event Command Structure
```typescript
{
code: number; // Command code (see RPG Maker MZ documentation)
indent: number; // Indentation level
parameters: any[]; // Command parameters
}
```
## Common Event Command Codes
- `101` - Show Text
- `102` - Show Choices
- `111` - Conditional Branch
- `112` - Loop
- `113` - Break Loop
- `121` - Control Switches
- `122` - Control Variables
- `125` - Change Gold
- `126` - Change Items
- `201` - Transfer Player
- `356` - Plugin Command
For a complete list, refer to the RPG Maker MZ documentation.
## Development
### Building
```bash
npm run build
```
### Watch Mode
```bash
npm run dev
```
## Project 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.md
```
## Safety and Best Practices
1. **Backup Your Project**: Always backup your RPG Maker MZ project before making changes
2. **Close RPG Maker MZ Editor**: Close the RPG Maker MZ editor when using this server to avoid conflicts
3. **Validate Changes**: Test your game after making changes to ensure everything works correctly
4. **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 editor is closed when using it
- Some advanced features may require manual editing in the RPG Maker MZ editor
- Plugin-specific data structures may not be fully supported
## Troubleshooting
### "Invalid RPG Maker MZ project path"
Make sure the `RPGMAKER_PROJECT_PATH` environment variable points to a valid RPG Maker MZ project directory containing:
- `game.rmmzproject` file
- `data/` directory with `System.json`
### Changes Not Appearing
1. Make sure the RPG Maker MZ editor is closed
2. Verify the project path is correct
3. 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
- [RPG Maker MZ Official Website](https://www.rpgmakerweb.com/products/rpg-maker-mz)
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [RPG Maker MZ Database Structure](https://github.com/rpgtkoolmv/rmmz-api-reference)
## Support
For issues and feature requests, please open an issue on the project repository.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
firecrawl
Firecrawl MCP Server enables web scraping, crawling, and content extraction.
servers
Model Context Protocol Servers
Time
A Model Context Protocol server for time and timezone conversions.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
Sequential Thinking
A structured MCP server for dynamic problem-solving and reflective thinking.