Content
# 🎮 RPG Maker MZ MCP Server
<div align="center">
**MCP Server for Complete RPG Maker MZ Game Development**
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
**Fully create RPG games with MCP tools + AI image generation support!**
📖 **[Beginner's Guide](./GETTING_STARTED.md)** | [Features](#-features) • [Installation](#-setup) • [Examples](#-examples) • [Tool List](#-available-tools)
</div>
## 🌟 Features
This MCP server programmatically provides a **complete game development environment for RPG Maker MZ**. You can create full-fledged RPG games using code or AI agents without opening the GUI.
### 🎯 Key Features
- 🤖 **🆕 Autonomous Fully Automatic Game Creation**: Generate a complete RPG in 3-7 minutes just by entering a concept!
- 🚀 **Complete Project Creation**: Generate RPG Maker MZ projects from scratch
- 🗺️ **Map Editor**: Programmatically edit maps and tiles
- 🎭 **Event System**: Implement complex game events and stories
- 📊 **Database Management**: Edit all data such as actors, skills, items, etc.
- 🎨 **AI Image Generation**: Automatically generate game assets with Gemini 2.5 Flash (nanobanana)
- 📖 **AI Scenario Generation**: Automatically generate complete stories, maps, and events with the Gemini API
- 🔧 **MCP Integration**: Complete toolchain using Model Context Protocol
### 🤖 Autonomous Fully Automatic Game Creation (NEW!)
**Generate a complete RPG with just one line of command!**
```bash
npx rpgmaker-mz-mcp auto-create "/games/MyRPG" "fantasy adventure with dragons"
```
**Or with Claude Code:**
```
Automatically generate an RPG with the concept "cyberpunk detective story"
```
**8 steps that are executed automatically:**
1. ✅ Project Creation
2. ✅ Concept Analysis
3. ✅ Scenario Generation (Map/Character/Event)
4. ✅ Battle System (Enemy/Skill)
5. ✅ Quest System
6. ✅ AI Image Asset Generation
7. ✅ Status Balance Adjustment
8. ✅ Project Optimization
**⏱️ Time required: 3-7 minutes → Ready to play!**
See [AUTONOMOUS_CREATION.md](./AUTONOMOUS_CREATION.md) for details.
### 🎨 AI Image Generation (NEW!)
Automatically generate assets for RPG Maker MZ using the Gemini 2.5 Flash API:
- **Character Sprites** (144x192px, 3x4 grid)
- **Face Graphics** (144x144px, 2x2 grid)
- **Tilesets** (768x768px)
- **Battlebacks** (1000x740px)
- **Enemy Graphics** (816x624px)
- **Side View Battlers** (576x384px, 9x6 grid)
- **Pictures** (816x624px)
## 📦 Available Tools
### 🎮 Project Management
| Tool | Description |
|--------|------|
| `create_project` | Create a new project |
| `list_projects` | Display a list of projects |
| `read_project_info` | Read project information |
| `generate_project_context` | Generate context document |
| `analyze_project_structure` | Analyze project structure |
| `extract_game_design_patterns` | Extract game design patterns |
### 🗺️ Map Editing
| Tool | Description |
|--------|------|
| `create_map` | Create a new map |
| `list_maps` | Display a list of maps |
| `read_map` | Read map data |
| `update_map_tile` | Update tile |
### 🎭 Event Editing
| Tool | Description |
|--------|------|
| `add_event` | Add event |
| `add_event_command` | Add event command |
**Supported event command examples:**
- `101` - Show Text
- `201` - Player Movement
- `122` - Variable Operation
- `111` - Conditional Branch
- Supports all other RPG Maker MZ commands
### 📊 Database Editing
| Tool | Description |
|--------|------|
| `add_actor` | Add actor |
| `add_class` | Add class |
| `add_skill` | Add skill |
| `add_item` | Add item |
| `update_database` | Update all databases |
### 🎨 AI Image Generation
| Tool | Description |
|--------|------|
| `generate_asset` | Generate asset with Gemini 2.5 Flash |
| `generate_asset_batch` | Batch generation of multiple assets |
| `describe_asset` | AI analysis of existing assets |
### 🤖 Autonomous Game Creation (NEW!)
| Tool | Description |
|--------|------|
| `autonomous_create_game` | Automatically generate a complete RPG from a concept (8 steps fully automatic) |
### 📖 AI Scenario Generation
| Tool | Description |
|--------|------|
| `generate_scenario` | Generate a complete RPG scenario with Gemini AI |
| `implement_scenario` | Implement the generated scenario in the project |
| `generate_and_implement_scenario` | Generate and implement a scenario in one step |
| `generate_scenario_variations` | Generate multiple scenario variations |
### 🔌 Plugin Management
| Tool | Description |
|--------|------|
| `list_plugins` | Display a list of plugins |
## 🚀 Setup
### Prerequisites
- Node.js 18 or higher
- npm or yarn
- Gemini API Key (if using AI image generation)
### Installation
```bash
# Clone the repository
git clone https://github.com/ShunsukeHayashi/rpgmaker-mz-mcp.git
cd rpgmaker-mz-mcp
# Install dependencies
npm install
# Build
npm run build
```
### MCP Configuration
Add to the configuration file of Claude Desktop or another MCP client:
```json
{
"mcpServers": {
"rpgmaker-mz": {
"command": "node",
"args": ["/path/to/rpgmaker-mz-mcp/dist/index.js"],
"env": {
"GEMINI_API_KEY": "your-gemini-api-key-here"
}
}
}
}
```
### Environment Variables
If using the AI image generation function, set the following environment variables:
```bash
export GEMINI_API_KEY="your-api-key"
```
## 💡 Examples
### Basic Game Creation Flow
```typescript
// 1️⃣ Create Project
create_project({
project_path: "/path/to/MyFantasyRPG",
game_title: "Fantasy Adventure"
})
// 2️⃣ Create Map
create_map({
project_path: "/path/to/MyFantasyRPG",
map_id: 2,
name: "Town Square",
width: 25,
height: 20
})
// 3️⃣ Add NPC Event
add_event({
project_path: "/path/to/MyFantasyRPG",
map_id: 2,
event_id: 1,
name: "Town Elder",
x: 12,
y: 10
})
// 4️⃣ Add Conversation Event
add_event_command({
project_path: "/path/to/MyFantasyRPG",
map_id: 2,
event_id: 1,
page_index: 0,
code: 101, // Show Text
parameters: ["", 0, 0, 2]
})
add_event_command({
project_path: "/path/to/MyFantasyRPG",
map_id: 2,
event_id: 1,
page_index: 0,
code: 401, // Text continuation
parameters: ["Welcome to our town, traveler!"]
})
// 5️⃣ Add Player Character
add_actor({
project_path: "/path/to/MyFantasyRPG",
id: 1,
name: "Hero"
})
add_class({
project_path: "/path/to/MyFantasyRPG",
id: 1,
name: "Warrior"
})
```
### 🎨 AI Image Generation Example
```typescript
// Generate Character Sprite
generate_asset({
project_path: "/path/to/MyFantasyRPG",
asset_type: "character",
prompt: "A brave knight with silver armor and red cape, pixel art style, walking animation sprite sheet",
filename: "Knight.png"
})
// Generate Face Graphic
generate_asset({
project_path: "/path/to/MyFantasyRPG",
asset_type: "face",
prompt: "Female mage with blue robes and long purple hair, multiple expressions (normal, happy, sad, angry)",
filename: "Mage_Face.png"
})
// Batch Generation
generate_asset_batch({
requests: [
{
project_path: "/path/to/MyFantasyRPG",
asset_type: "enemy",
prompt: "Fire dragon boss, menacing pose",
filename: "Dragon.png"
},
{
project_path: "/path/to/MyFantasyRPG",
asset_type: "enemy",
prompt: "Goblin warrior with wooden club",
filename: "Goblin.png"
}
]
})
// Existing Asset Analysis
describe_asset({
project_path: "/path/to/MyFantasyRPG",
asset_type: "character",
filename: "Knight.png"
})
// → "This character sprite shows a knight in silver armor..."
```
### 📖 AI Scenario Automatic Generation (Super Powerful!)
```typescript
// Generate a complete RPG with one command!
generate_and_implement_scenario({
project_path: "/path/to/MyFantasyRPG",
theme: "medieval fantasy adventure with dragons",
style: "epic and heroic",
length: "medium"
})
// Content to be generated:
// - Story and world view
// - Maps (towns, dungeons, fields, etc.)
// - Characters (protagonist, companions, NPCs)
// - Events (conversations, quests, battles)
// - Items and skills
// Everything is implemented automatically!
// Generate and compare multiple variations
generate_scenario_variations({
project_path: "/path/to/MyFantasyRPG",
theme: "cyberpunk detective story",
style: "noir and mysterious",
length: "short",
count: 3
})
// → Generate 3 different stories and select the best one
```
### 📊 Project Analysis
```typescript
// Project Structure Analysis
analyze_project_structure({
project_path: "/path/to/MyFantasyRPG"
})
// Context Generation
generate_project_context({
project_path: "/path/to/MyFantasyRPG",
include_maps: true,
include_events: true,
include_plugins: true
})
// Design Pattern Extraction
extract_game_design_patterns({
project_path: "/path/to/MyFantasyRPG"
})
```
## 🎯 Use Cases
### 1. 🤖 Fully Automatic Game Generation
```
"Create a fantasy RPG" → AI automatically generates story, maps, characters, and events!
```
### 2. 🎨 AI-Driven Development Workflow
```
Scenario generation → Asset generation → Implementation → Completion
All supported by AI
```
### 3. 📚 Mass Generation of Game Prototypes
```
Try multiple story concepts and choose the best one
```
### 4. 🔄 Programmatic Game Development
```
Generate games from Python scripts or workflow tools
```
### 5. 🧪 Automatic Test Data Generation
```
Instantly create a test project for the game engine
```
### 6. 🎓 Education/Learning
```
Automatically generate learning samples for RPG Maker MZ
```
## 📊 Development Status
| Feature | Status |
|------|------|
| ✅ Project Creation/Management | Completed |
| ✅ Map Creation/Editing | Completed |
| ✅ Event Creation/Editing | Completed |
| ✅ Database Editing | Completed |
| ✅ AI Image Generation (Gemini 2.5 Flash) | Completed |
| ✅ AI Scenario Automatic Generation | **NEW!** |
| ✅ Context Engineering | Completed |
| ✅ Complete Game Creation Workflow | Completed |
## 🌟 Special Features
### 🚀 One-Command RPG Generation
```bash
# A complete RPG game is generated with just one command
generate_and_implement_scenario({
theme: "your game idea",
style: "your preferred style",
length: "short"
})
# → A playable RPG is completed in minutes!
```
### 🎨 Fully AI-Driven Development
- **Scenario**: Automatically generated by Gemini AI
- **Assets**: Gemini 2.5 Flash generates images
- **Implementation**: MCP tools automatically implement
- **Result**: Fully working RPG Maker MZ project
## 🤝 Contribution
Pull Requests are welcome!
## 📄 License
MIT License
## 🔗 Links
- [RPG Maker MZ Official](https://rpgmakerofficial.com/product/mz/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Gemini API](https://ai.google.dev/)
---
<div align="center">
**🎮 Fully create RPG Maker MZ games with MCP tools! 🎮**
Made with ❤️ by [ShunsukeHayashi](https://github.com/ShunsukeHayashi)
</div>
