MapleStory MCP Server
An MCP (Model Context Protocol) server that wraps the Nexon MapleStory OpenAPI, allowing AI assistants to query MapleStory game data including character info, rankings, union, guild, and more.
Features
- Character - Basic info, stats, equipment, skills, V/HEXA matrix, Dojang records
- Union - Union level, raider layout, artifact info
- Guild - Guild search and basic info
- Ranking - Overall, union, guild, Dojang, The Seed, achievement rankings
- History - Starforce, cube, potential re-roll history
- Notice - Official notices, updates, events, cash shop notices
Prerequisites
- Python 3.13+
- uv package manager
- MapleStory API key from Nexon OpenAPI
Installation
# Clone the repository
git clone https://github.com/kcw2034/maplestory-mcp-server.git
cd maplestory-mcp-server
# Install dependencies
uv sync
Configuration
Create a .env file in the project root:
MAPLESTORY_API_KEY=your_api_key_here
You can get an API key by registering an app at Nexon OpenAPI.
Usage
Running the server
uv run server.py
Claude Desktop configuration
Add this to your Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"maplestory": {
"command": "uv",
"args": ["run", "server.py"],
"cwd": "/path/to/maplestory-mcp-server",
"env": {
"MAPLESTORY_API_KEY": "your_api_key_here"
}
}
}
}
Available Tools
| Category | Tool | Description |
|---|---|---|
| Character | get_character_ocid | Look up character OCID by name |
| Character | get_character_basic | Basic info (level, class, world, guild) |
| Character | get_character_stat | Combined stats (STR, DEX, combat power) |
| Character | get_character_item_equipment | Equipped items |
| Character | get_character_skill | Skill info by grade |
| Character | get_character_hexamatrix | HEXA matrix (6th job skills) |
| Union | get_union | Union level and grade |
| Union | get_union_raider | Union raider layout and effects |
| Guild | get_guild_id | Look up guild ID by name and world |
| Guild | get_guild_basic | Guild basic info |
| Ranking | get_ranking_overall | Overall ranking |
| Ranking | get_ranking_dojang | Mu Lung Dojang ranking |
| History | get_history_starforce | Starforce enhancement history |
| Notice | get_notices | Official notice list |
See
server.pyfor the full list of 30+ tools.