k4zuki0539/-rpgmaker-mz-mcp

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

npm install
npm run build

Configuration

Set the RPG Maker MZ 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/project

Usage

Running the Server

npm start

Or directly:

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

{
  "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

{
  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 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

npm run build

Watch Mode

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
• Model Context Protocol Documentation
• RPG Maker MZ Database Structure

Support

For issues and feature requests, please open an issue on the project repository.