Skip to main content
Glama
RPG Maker MZ/MV MCP Server

RPG Maker MZ/MV MCP Server

by garuh143

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 build

Configuration

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/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/MV project:

Example 1: Get All Actors

Show me all actors in my RPG Maker MZ/MV 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/MV 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/MV 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/MV project before making changes

  2. Close RPG Maker MZ/MV Editor: Close the RPG Maker MZ/MV 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/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.rmmzproject file (MZ) or Game.rpgproject file (MV)

  • data/ directory with System.json

Changes Not Appearing

  1. Make sure the RPG Maker MZ/MV 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

Support

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

Available Tools

37 tools
add_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

    C2.6/5.0

    Scored across 37 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers