mcp server

maplestory-mcp-server

MCP server for MapleStory OpenAPI - query character info, rankings, union, guild and more

kcw2034/maplestory-mcp-servercommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "maplestory-mcp-server": {
      "command": "uvx",
      "args": [
        "maplestory-mcp-server"
      ],
      "env": {
        "MAPLESTORY_API_KEY": "<your MAPLESTORY_API_KEY>"
      }
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 17, 2026

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.py for the full list of 30+ tools.

License

MIT