MapleStory

You can run a MapleStory MCP Server to access Nexon Open API data in a structured way for character, union, guild, rankings, and game mechanics. This server lets you query up-to-date MapleStory data and use it with MCP-enabled clients for rich, AI-assisted workflows.

How to use

Install and run the MCP server, then connect your MCP client to retrieve character data, union details, guild information, rankings, cube and starforce probabilities, and system notices. You can query for single characters or broader leaderboards, and integrate the data into your apps or AI agents.

How to install

Prerequisites: Node.js 18 or newer, npm, and an API key for the Nexon Open API.

1. Install the MCP server globally.

npm install -g maplestory-mcp-server

2. Run the server using NPX (recommended) with your Nexon API key.

npx maplestory-mcp-server --api-key YOUR_NEXON_API_KEY

Configuration for Claude Desktop (example)

To enable Claude Desktop to use the MapleStory MCP Server, add a startup configuration that runs the MCP server locally.

{
  "mcpServers": {
    "maplestory-mcp-server": {
      "command": "npx",
      "args": ["-y", "maplestory-mcp-server"],
      "env": {
        "NEXON_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Additional configuration notes

• Ensure you replace YOUR_API_KEY_HERE with the actual Nexon API key you obtain from the Nexon Open API portal.

Commands and options you can use

The server supports a straightforward NPX startup and optional environment configuration. You can start and test the service quickly, then integrate with your preferred MCP client.

Troubleshooting and tips

If you encounter issues, verify that the API key is valid and properly set in the environment. Ensure the command and arguments in your startup configuration match the examples above. If requests exceed limits, wait briefly and retry. Use debug mode to diagnose problems.

npx maplestory-mcp-server --api-key YOUR_NEXON_API_KEY --debug

API tools and endpoints

You can query a wide range of MapleStory data through the MCP interface. The tools cover character basics, detailed stats, equipment, union information, guild data, rankings, notices, and probability data for cube and starforce upgrades.

Security and best practices

Keep your Nexon API key secure and avoid embedding it in client-side code. Use environment variables to configure keys on the server side, and rotate keys if you suspect exposure. Monitor usage to stay within rate limits and implement retries with backoff for transient failures.

Notes on supported features

The server provides character data, union details, guild information, rankings, game mechanism data, notices, TypeScript typing support, comprehensive logging, and robust error handling to help you build reliable MCP-powered experiences.

Available tools

get_character_basic_info

Fetches basic information about a character including name, level, class, world, and guild.

get_character_stats

Retrieves detailed character stats including base stats, combat stats, defenses, and full stat breakdown.

get_character_equipment

Returns the character's equipment and item details.

get_character_full_info

Provides a comprehensive view of a character in a single call.

get_union_info

Fetches union level, grade, and artifact information for a character.

get_union_raider

Gets union raid board composition and blocks.

get_union_ranking

Retrieves union power rankings.

get_guild_info

Provides guild information, members, and skills.

get_guild_ranking

Fetches guild level rankings.

get_overall_ranking

Retrieves overall rankings with filtering options.

get_notice_list

Lists game notices and announcements.

get_notice_detail

Retrieves detailed notice information.

get_cube_probability

Provides cube enhancement probability data.

get_starforce_probability

Provides Star Force enhancement probability data.

health_check

Checks API connectivity and health.