MapleStory MCP Server

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. **AP