maplestory

MapleStory MCP Server 🍁 제공은 메이플스토리 오픈 API 데이터를 통합적으로 조회하고 Claude Desktop 및 기타 MCP 도구에서 사용할 수 있도록 구조화된 인터페이스를 제공합니다. 서버를 시작하면 캐릭터 정보, 유니온, 길드, 랭킹, 게임 메커니즘 관련 도구를 통해 특정 캐릭터나 월드에 대한 상세 데이터를 요청하고 응답받을 수 있습니다. 사용자는 캐릭터의 기본 정보, 스탯, 장비, 유니온 정보, 길드 정보, 공지사항, 큐브 및 스타포스 확률 등 다양한 API 도구를 활용해 정교한 대화형 질의응답을 구성할 수 있습니다. 또한 TypeScript로 타입 안전성을 보장하며, 로깅과 오류 처리에 대한 명확한 메시지를 제공합니다.

주요 도구 목록:

• 캐릭터 도구: get_character_basic_info, get_character_stats, get_character_equipment, get_character_full_info
• 유니온 도구: get_union_info, 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, health_check

클라우드 데스크를 통한 연동 시, NEXON API 키를 발급받아 환경 변수에 설정하고, Claude Desktop의 설정 파일에 mcpServers 항목으로 서버를 등록합니다. 예시 설정은 다음과 같습니다: 설정 파일에 maplestory-mcp-server를 추가하고 NEXON_API_KEY를 입력합니다. 설정 변경 후 Claude Desktop을 재시작하면 대화에서 메이플스토리 관련 질문에 응답하도록 연결이 확인됩니다.

실제 예시 질의:

• 캐릭터 기본 정보 알려줘: "김코인 캐릭터의 기본 정보를 알려줘"
• 유니온 정보 조회: "스카니아용사 캐릭터의 유니온 정보를 조회해줘"
• 월드 랭킹 조회: "스카니아 월드의 아크메이지 랭킹 1페이지를 보여줘"
• 큐브 확률 확인: "레드 큐브 강화 확률 정보를 알려줘"

필수 선행사항

• Node.js 18+가 시스템에 설치되어 있어야 합니다.
• npm 또는 pnpm이 사용 가능해야 합니다.
• Git이 설치되어 있어야 저장소를 클론할 수 있습니다.

설치 단계

1. 저장소 클론 git clone https://github.com/ljy9303/maplestory-mcp-server.git
2. 프로젝트 디렉토리로 이동 cd maplestory-mcp-server
3. 의존성 설치 npm install
4. 빌드(타입스크립트 컴파일 및 준비) npm run build
5. 서버 실행 방법
   • NPX 사용 권장 방법으로 실행하려면 아래 명령을 사용합니다. npx maplestory-mcp-server --api-key YOUR_NEXON_API_KEY
   • 또는 로컬 개발 서버를 실행하려면 빌드 후 시작 스크립트를 사용합니다. npm run dev

환경 변수 및 설정

• NEXON_API_KEY: NEXON 오픈 API 키. Claude Desktop 설정 또는 실행 시 인자로 전달.
• LOG_LEVEL: 로깅 레벨 (예: info, debug)
• NODE_ENV: 환경 (development/production)

일반 팁 및 주의사항:

• API 키 노출을 피하기 위해 공개 저장소에 API 키를 커밋하지 마세요.
• Claude Desktop에서 mcp-maple 서버를 인식하지 못하는 경우 설정 파일 경로와 JSON 형식을 재차 확인하세요.
• API 호출 제한은 하루 500회, 초당 1회 요청으로 설정되어 있습니다. 필요 시 캐싱 전략 및 요청 간격 정책을 적용하세요.
• 서버 포트와 버전은 CLI 옵션으로 조정 가능하며, 필요 시 env 또는 설정 파일을 통해 세부 구성을 확장할 수 있습니다.