MapleStory MCP Server 🍁

NEXON 메이플스토리 오픈 API 데이터에 접근할 수 있는 종합적인 MCP(Model Context Protocol) 서버입니다. 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 키를 발급받으세요:

1. NEXON 계정으로 로그인
2. "개발자 센터" → "애플리케이션 관리" 이동
3. "새 애플리케이션 등록" 클릭
4. 애플리케이션 정보 입력 후 등록
5. 생성된 API 키 복사

2. Claude Desktop 설정 파일 찾기

운영체제별 설정 파일 위치:

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

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

Linux:

~/.config/Claude/claude_desktop_config.json

3. 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 - 유니온 레벨, 등급, 아티팩트 정보 조회
• 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 - API 연결 및 상태 확인

📖 사용 예시

🎯 Claude Desktop에서 질문하기

Claude Desktop에서 다음과 같은 자연어로 메이플스토리 정보를 조회할 수 있습니다:

캐릭터 정보 조회

"김코인"이라는 캐릭터의 기본 정보를 알려줘

"베라월드용사" 캐릭터의 상세한 스탯 정보를 조회해줘

"리부트용사" 캐릭터가 착용하고 있는 장비 목록을 보여줘

유니온 및 길드 정보

"스카니아용사" 캐릭터의 유니온 정보를 조회해줘

"스카니아" 월드의 "길드명" 길드 정보를 알려줘

랭킹 조회

스카니아 월드의 아크메이지(불,독) 직업 랭킹 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: "스카니아용사"
});

유니온 및 길드 데이터

// 유니온 정보 조회
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 키 얻기

상세 가이드

1. NEXON 오픈 API 포털 접속

   • https://openapi.nexon.com/ 방문

2. 계정 생성 및 로그인

   • NEXON 계정으로 로그인 (게임 계정과 동일)
   • 계정이 없다면 회원가입 진행

3. 개발자 센터 이동

   • 상단 메뉴에서 "개발자 센터" 클릭
   • "애플리케이션 관리" 선택

4. 새 애플리케이션 등록

   • "새 애플리케이션 등록" 버튼 클릭
   • 필수 정보 입력:
     • 애플리케이션 이름: MCP Maple (예시)
     • 애플리케이션 설명: Claude Desktop MCP 서버용
     • 서비스 URL: http://localhost (개발용)

5. API 키 발급 및 복사

   • 등록 완료 후 API 키 확인
   • API 키 복사 (보안을 위해 안전한 곳에 저장)

6. API 키 사용

   • Claude Desktop 설정에서 NEXON_API_KEY로 사용
   • 또는 CLI에서 --api-key 매개변수로 사용

💡 팁: API 키는 외부에 노출되지 않도록 주의하세요. GitHub 등 공개 저장소에 업로드하지 마세요.

🎮 지원되는 게임 및 월드

메이플스토리 월드

• 스카니아 (Scania)
• 베라 (Bera)
• 루나 (Luna)
• 제니스 (Zenith)
• 크로아 (Croa)
• 유니온 (Union)
• 엘리시움 (Elysium)
• 이노시스 (Enosis)
• 레드 (Red)
• 오로라 (Aurora)
• 아케인 (Arcane)
• 노바 (Nova)
• 리부트 (Reboot)
• 리부트2 (Reboot2)

🚦 요청 제한 및 모범 사례

• 요청 제한: API 키당 하루 500회 요청
• 요청 빈도: 초당 최대 1회 요청
• 데이터 갱신: 캐릭터 데이터는 매일 업데이트
• 캐시: 더 나은 성능을 위한 결과 캐싱
• 오류 처리: 일시적 실패에 대한 자동 재시도

🧪 개발

전제 조건

• 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, MP
• combatStats: 공격력, 마력, 크리티컬 스탯
• defenseStats: 물리/마법 방어 스탯
• allStats: 완전한 스탯 분석

유니온 도구

get_union_info

유니온 레벨, 등급, 아티팩트 정보를 조회합니다.

매개변수:

• characterName (string, 필수): 조회할 캐릭터 이름
• date (string, 선택사항): YYYY-MM-DD 형식의 날짜

반환값:

• unionLevel: 현재 유니온 레벨
• unionGrade: 유니온 등급/랭크
• unionArtifact: 아티팩트 레벨 및 포인트

오류 처리

모든 도구는 일관된 오류 정보를 반환합니다:

{
  success: false,
  error: "오류 설명",
  metadata?: {
    executionTime: number,
    apiCalls: number
  }
}

🤝 기여하기

기여를 환영합니다! 자세한 내용은 기여 가이드를 읽어주세요.

개발 프로세스

1. 저장소를 포크합니다
2. 기능 브랜치를 생성합니다
3. 변경사항을 작성합니다
4. 테스트를 추가합니다
5. 모든 테스트가 통과하는지 확인합니다
6. 풀 리퀘스트를 제출합니다

📄 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🙏 감사의 말

• 메이플스토리 오픈 API를 제공해 주신 NEXON
• MCP 사양을 제공해 주신 Model Context Protocol
• Claude 및 MCP 도구를 제공해 주신 Anthropic

🔧 문제 해결

일반적인 문제들

1. Claude Desktop에서 mcp-maple이 인식되지 않는 경우

증상: Claude Desktop에서 메이플스토리 관련 질문을 해도 응답하지 못함

해결방법:

1. Claude Desktop을 완전히 종료
2. 설정 파일 경로가 올바른지 확인:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
3. JSON 형식이 올바른지 확인 (쉼표, 괄호 등)
4. Claude Desktop 재시작

2. API 키 오류

증상: "API key is invalid" 또는 "Authentication failed" 오류

해결방법:

1. NEXON 오픈 API 포털에서 API 키 상태 확인
2. API 키가 만료되지 않았는지 확인
3. 설정 파일에서 API 키가 올바르게 입력되었는지 확인
4. API 키 앞뒤 공백 제거

3. 캐릭터를 찾을 수 없는 경우

증상: "Character not found" 오류

해결방법:

1. 캐릭터 이름을 정확히 입력 (대소문자, 특수문자 포함)
2. 해당 캐릭터가 실제로 존재하는지 게임에서 확인
3. 캐릭터가 최근에 생성된 경우 하루 정도 기다린 후 재시도

4. 요청 제한 초과

증상: "Rate limit exceeded" 오류

해결방법:

1. 잠시 기다린 후 재시도 (1분 정도)
2. 요청 빈도를 줄여서 사용
3. 하루 500회 제한을 초과하지 않도록 주의

5. 네트워크 연결 문제

증상: "Network error" 또는 "Timeout" 오류

해결방법:

1. 인터넷 연결 상태 확인
2. 방화벽이나 프록시 설정 확인
3. 잠시 후 재시도

디버깅 방법

1. 상세한 로그 확인

npx mcp-maple --debug --api-key YOUR_API_KEY

2. 연결 테스트

Claude Desktop에서 다음과 같이 입력하여 연결 상태를 확인:

메이플스토리 API 연결 상태를 확인해줘

3. 설정 파일 검증

JSON 형식이 올바른지 온라인 JSON 검증기에서 확인하세요.

알려진 제한 사항

• API 호출 제한: 하루 500회, 초당 1회
• 데이터 갱신: 캐릭터 정보는 매일 오전 8시경 업데이트
• 지원 월드: 일부 테스트 서버나 특수 월드는 지원되지 않을 수 있음

📞 지원

• 이슈: GitHub Issues
• 문서: API 참조
• 예시: 사용 예시

🔗 관련 프로젝트

• MCP TypeScript SDK
• Claude Desktop
• NEXON 오픈 API

---

메이플스토리 커뮤니티를 위해 ❤️로 제작되었습니다