io.github.kcw2034/maplestory-mcp-server
MCP server for Nexon MapleStory OpenAPI - character, rankings, union, guild, and notices
Open source Open in the app JSON README (API)
About
MCP server for Nexon MapleStory OpenAPI - character, rankings, union, guild, and notices
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- kcw2034
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.1
- Last push
- 2026-03-26T08:09:53Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:20
- Updated
- 2026-08-29 04:00:20
- Origin id
io.github.kcw2034/maplestory-mcp-server
README
# MapleStory MCP Server
An MCP (Model Context Protocol) server that wraps the [Nexon MapleStory OpenAPI](https://open.api.nexon.com), 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](https://docs.astral.sh/uv/) package manager
- MapleStory API key from [Nexon OpenAPI](https://open.api.nexon.com)
## Installation
```bash
# 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:
```env
MAPLESTORY_API_KEY=your_api_key_here
```
You can get an API key by registering an app at [Nexon OpenAPI](https://open.api.nexon.com).
## Usage
### Running the server
```bash
uv run server.py
```
### Claude Desktop configuration
Add this to your Claude Desktop config (`claude_desktop_config.json`):
```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.py` for the full list of 30+ tools.
## License
[MIT](LICENSE)
<!-- mcp-name: io.github.kcw2034/maplestory-mcp-server -->