](https://lobehub.com/mcp/ljy9303-maplestory-mcp-server)
MapleStory MCP服务器🍁
NEXON Maple Story是一款全面的模型上下文协议（MCP）服务器，可访问开放API数据。通过Claude Desktop和其他MCP兼容的AI助手，为角色信息、联合详细信息、行会数据、排名和游戏机制提供结构化访问。
功能
- 角色信息：查看详细的角色定位器、装备、基本信息
- 联合系统：联合攻击队构成及排名接近
- 行会管理：查询行会信息和成员详细信息
- 排名：访问各种排行榜和竞争数据
- 游戏机制：关于魔方和星际争霸强化概率
- 游戏更新：最新公告和发布
- TypeScript支持：完全类型安全性和IntelliSense支持
- 全面记录：详细的调试操作日志记录
- 错误处理：强大的错误处理和详细的错误消息
🚀 快速入门
使用NPX（建议）
npx maplestory-mcp-server --api-key YOUR_NEXON_API_KEY设置
npm install -g maplestory-mcp-server🖥️ 与Claude Desktop一起使用
1.准备NEXON API密钥
首先 NEXON开放API门户从获得API密钥：
- 使用NEXON帐户登录
- 移动“开发者中心”→“应用程序管理”
- 单击“注册新应用程序”
- 输入应用程序信息后注册
- 复制生成的API密钥
2.查找Claude Desktop配置文件
特定于操作系统的配置文件位置：
窗户：
%APPDATA%\Claude\claude_desktop_config.jsonmacOS：
~/Library/Application Support/Claude/claude_desktop_config.jsonLinux：
~/.config/Claude/claude_desktop_config.json3.添加MCP服务器设置
在配置文件中添加或修改以下内容：
{
"mcpServers": {
"maplestory-mcp-server": {
"command": "npx",
"args": ["-y", "maplestory-mcp-server"],
"env": {
"NEXON_API_KEY": "여기에_발급받은_API_키_입력"
}
}
}
}⚠️ 重要: YOUR_NEXON_API_KEY用实际获得的API密钥替换。4.重新启动Claude Desktop
修改配置文件后，请完全退出并重新启动Claude Desktop。
5.确认连接
Claude Desktop重新启动后，在新对话中输入以下内容以确认连接：
메이플스토리 API가 정상적으로 작동하는지 확인해줘成功连接后，Claude可以回答有关枫叶故事的问题！
🛠️ 可用的MCP工具
角色工具
get_character_basic_info-查询基本角色信息（等级，职业，世界，行会）get_character_stats-查看详细的角色属性和战斗属性get_character_equipment-查看角色装备及物品详细信息get_character_full_info-一次查看综合角色信息
联合工具
get_union_info-查看Union级别、等级和工件信息get_union_raider-组合攻击台主板配置和块查询get_union_ranking-查看联合力量排名
行会工具
get_guild_info-查询行会信息、成员、技能get_guild_ranking-查询行会等级排名
排名工具
get_overall_ranking-查看包含筛选选项的综合等级排名
实用工具
get_notice_list-查看游戏公告和发布get_notice_detail-查看详细的公告信息get_cube_probability-查询魔方强化概率信息get_starforce_probability-查看StarForce强化概率信息health_check-检查API连接和状态
📖 使用示例
🎯 在Claude Desktop中提问
在Claude Desktop中，您可以使用以下自然语言查询枫叶故事信息：
查询角色信息
"김코인"이라는 캐릭터의 기본 정보를 알려줘"베라월드용사" 캐릭터의 상세한 스탯 정보를 조회해줘"리부트용사" 캐릭터가 착용하고 있는 장비 목록을 보여줘Union和公会信息
"스카니아용사" 캐릭터의 유니온 정보를 조회해줘"스카니아" 월드의 "길드명" 길드 정보를 알려줘查询排名
스카니아 월드의 아크메이지(불,독) 직업 랭킹 1페이지를 보여줘베라 월드의 유니온 랭킹 상위 20명을 조회해줘游戏信息
메이플스토리 최신 공지사항을 확인해줘레드 큐브의 강화 확률 정보를 알려줘💡 使用技巧
1.角色综合分析
"스카니아용사" 캐릭터의 모든 정보를 종합적으로 분석해줘 (기본정보, 스탯, 장비, 유니온)2.行会管理
"베라" 월드의 "우리길드" 길드원들의 레벨과 직업을 정리해줘3.排名比较
"스카니아" 월드와 "베라" 월드의 상위 랭커들을 비교 분석해줘4.跟踪进度
"내캐릭터" 캐릭터의 어제와 오늘 스탯 변화를 비교해줘🔧 编程示例
开发人员的直接API调用示例：
查询角色信息
// 기본 캐릭터 정보 조회
const basicInfo = await getCharacterBasicInfo({
characterName: "스카니아용사"
});
// 상세한 캐릭터 스탯 조회
const stats = await getCharacterStats({
characterName: "스카니아용사",
date: "2024-01-15"
});
// 캐릭터 장비 조회
const equipment = await getCharacterEquipment({
characterName: "스카니아용사"
});Union和公会数据
// 유니온 정보 조회
const unionInfo = await getUnionInfo({
characterName: "스카니아용사"
});
// 길드 정보 조회
const guildInfo = await getGuildInfo({
guildName: "길드명",
worldName: "스카니아"
});排名和排行榜
// 종합 랭킹 조회
const rankings = await getOverallRanking({
worldName: "스카니아",
className: "아크메이지(불,독)",
page: 1
});
// 유니온 랭킹 조회
const unionRankings = await getUnionRanking({
worldName: "스카니아",
page: 1
});🔧 设置
环境变量
NEXON_API_KEY-NEXON开放API密钥（必需）LOG_LEVEL-记录级别（默认为“info”）NODE_ENV-环境（development/production）
CLI选项
--api-key-NEXON API密钥--port-服务器端口（默认值：3000）--debug-启用调试记录--name-服务器名称（默认为“mcp-maple”）--version-服务器版本
🔑 获取NEXON API密钥
详细指南
- NEXON开放API门户连接
- https://openapi.nexon.com/ 访问
- 创建和登录帐户
- 使用NEXON帐户登录（与游戏帐户相同） - 如果您没有帐户，请继续注册会员。
- 移动开发者中心
- 在顶部菜单中单击“开发者中心” - 选择“应用程序管理”
- 注册新应用程序
- 单击“注册新应用程序”按钮 - 输入所需信息： - 应用程序名称: MCP Maple （示例） - 应用程序说明: Claude Desktop MCP 서버용 - 服务URL: http://localhost （用于开发）
- 发放和复制API密钥
- 注册完成后验证API密钥 - 复制API密钥（存储在安全的地方以确保安全）
- 使用API密钥
- 在Claude Desktop设置中 NEXON_API_KEY使用 - 或从CLI --api-key 用作参数
💡 提示：请注意不要将API密钥暴露在外部。不要上传到GitHub等公共存储库。
🎮 支持的游戏和世界
枫叶故事世界
- 斯堪尼亚（Scania）
- 베라 （贝拉）
- 露娜（Luna）
- 詹妮斯（Zenith）
- 克罗亚（Croa）
- 联合（Union）
- 埃利西姆（Elysium）
- 伊诺西斯（Enosis）
- 红色（Red）
- 极光（Aurora）
- 阿肯（Arcane）
- 诺瓦（Nova）
- 重新启动（Reboot）
- 重新启动2（Reboot 2）
🚦 请求限制和最佳实践
- 请求限制：每天请求500次API密钥
- 请求频率：每秒最多请求一次
- 数据更新：角色数据每天更新
- 缓存：缓存结果以获得更好的性能
- 错误处理：自动重试暂时失败
🧪 开发
前提条件
- Node.js 18+
- TypeScript 5.4+
- NEXON API密钥
设置
git clone https://github.com/ljy9303/maplestory-mcp-server.git
cd maplestory-mcp-server
npm install
npm run build构建
npm run build # TypeScript 빌드
npm run dev # 개발 모드 (watch)📚 API参考
角色信息工具
get_character_basic_info
查询基本角色信息，包括等级、职业、世界、行会。
参数：
characterName（string，必需）：要查询的角色名称date（string，可选）：YYYY-MM-DD格式的日期
返回值：
characterName：角色名称level：角色等级job：角色职业/等级world：世界/服务器名称guildName：行会名称（如果有）exp：当前经验值expRate：经验百分比
get_character_stats
查看详细的角色统计，包括伤害、暴击率、所有战斗属性。
参数：
characterName（string，必需）：要查询的角色名称date（string，可选）：YYYY-MM-DD格式的日期
返回值：
basicStats：STR、DEX、INT、LUK、HP、MPcombatStats：攻击力，魔力，暴击属性defenseStats：物理/魔法防御稳定器allStats：完全的静音分析
联合工具
get_union_info
查看联合级别、等级和物品信息。
参数：
characterName（string，必需）：要查询的角色名称date（string，可选）：YYYY-MM-DD格式的日期
返回值：
unionLevel：当前联合等级unionGrade：Union等级/等级unionArtifact：物品等级和积分
错误处理
所有工具都会返回一致的错误信息：
{
success: false,
error: "오류 설명",
metadata?: {
executionTime: number,
apiCalls: number
}
}🤝 贡献
欢迎您的贡献！有关详细信息，请访问 贡献指南请读一下。
开发过程
- 分叉存储库
- 创建功能分支
- 创建更改
- 添加测试
- 确保所有测试都通过
- 提交完整请求
📄 许可证
该项目根据MIT许可证进行许可。有关详细信息，请访问 许可证 请参考文件。
🙏 感谢的话
🔧 故障排除
常见问题
1.Claude Desktop无法识别mcp-maple
症状：Claude Desktop询问有关枫叶故事的问题时无法回答
解决方法:
- 完全关闭Claude Desktop
- 验证配置文件路径是否正确：
- 窗户： %APPDATA%\Claude\claude_desktop_config.json - macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json
- 检查JSON格式是否正确（逗号、括号等）
- 重新启动Claude Desktop
2.API密钥错误
症状：“API key无效”或“Authentication failed”错误
解决方法:
- NEXON开放API门户检查API密钥状态
- 验证API密钥是否过期
- 确保在配置文件中正确输入API密钥
- 消除API密钥前后的空格
3.找不到角色时
症状：“Character not found”错误
解决方法:
- 请输入正确的角色名称（包括大小写和特殊字符）
- 在游戏中确认该角色是否真的存在
- 如果角色最近创建，请等待一天后重试
4.请求超出限制
症状：错误“Rate limit excepted”
解决方法:
- 等待一段时间后重试（1分钟左右）
- 减少请求频率
- 注意每天不超过500次限制
5.网络连接问题
症状：“Network error”或“Timeout”错误
解决方法:
- 检查互联网连接状态
- 检查防火墙或代理设置
- 稍后重试
调试方法
1.查看详细日志
npx mcp-maple --debug --api-key YOUR_API_KEY2.测试连接
在Claude Desktop中输入以下内容以查看连接状态：
메이플스토리 API 연결 상태를 확인해줘3.验证配置文件
请在在线JSON验证器中检查JSON格式是否正确。
已知限制
- API调用限制：每天500次，每秒1次
- 数据更新：角色信息每天上午8点左右更新
- 支援世界：某些测试服务器或特殊世界可能不受支持
📞 支持
🔗 相关项目
______________________________________________________________________
为Maple Story社区制作的❤