About maplestory-mcp-server
A Nexon MapleStory OpenAPI wrapper for AI assistants, covering character data, rankings, union, guilds, history, and notices. It suits players seeking game information through MCP clients.
Key features
- 01Character stats and equipment
- 02Union and guild lookups
- 03Multiple ranking categories
- 04Enhancement history
- 05Official notices and events
Use cases
- 01Check a character’s stats and gear
- 02Compare ranking positions
- 03Look up union or guild details
- 04Review enhancement history and notices
MCP support
Exposes MapleStory data through MCP tools, including character, union, guild, ranking, history, and notice queries. MCP clients can run the server using the documented configuration.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
uvx maplestory-mcp-serverMAPLESTORY_API_KEYSecretAPI key from Nexon OpenAPI (https://open.api.nexon.com)Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
39Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| character_name | string | Yes | Character name |
Details
From the project READMEMapleStory 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.
License
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.