MapleStory MCP Server

Access NEXON MapleStory open API data for character info, union details, guild data, rankings, and game mechanics.

NEXON 메이플스토리 오픈 API 데이터에 접근할 수 있는 종합적인 MCP(Model Context Protocol) 서버입니다. Claude Desktop 및 기타 MCP 호환 AI 어시스턴트를 통해 캐릭터 정보, 유니온 세부사항, 길드 데이터, 랭킹, 게임 메커니즘에 구조화된 접근을 제공합니다.

- 캐릭터 정보: 상세한 캐릭터 스탯, 장비, 기본 정보 조회
- 유니온 시스템: 유니온 공격대 구성 및 랭킹 접근
- 길드 관리: 길드 정보 및 멤버 세부사항 조회
- 랭킹: 다양한 리더보드 및 경쟁 데이터 접근
- 게임 메커니즘: 큐브 및 스타포스 강화 확률 정보
- 게임 업데이트: 최신 공지사항 및 발표
- TypeScript 지원: 완전한 타입 안전성 및 IntelliSense 지원
- 종합적인 로깅: 디버깅을 위한 상세한 작업 로깅
- 오류 처리: 상세한 오류 메시지와 함께 강력한 오류 처리

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

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

%APPDATA%\Claude\claude_desktop_config.json

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

~/.config/Claude/claude_desktop_config.json

{ "mcpServers": { "maplestory-mcp-server": { "command": "npx", "args": ["-y", "maplestory-mcp-server"], "env": { "NEXON_API_KEY": "여기에_발급받은_API_키_입력" } } } }

⚠️중요:YOUR_NEXON_API_KEY를 실제 발급받은 API 키로 교체하세요.

설정 파일을 수정한 후 Claude Desktop을 완전히 종료했다가 다시 시작하세요.

Claude Desktop이 재시작되면 새 대화에서 다음과 같이 입력해 연결을 확인하세요:

성공적으로 연결되면 Claude가 메이플스토리 관련 질문에 답할 수 있습니다!

- 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에서 다음과 같은 자연어로 메이플스토리 정보를 조회할 수 있습니다:

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

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

"스카니아용사" 캐릭터의 모든 정보를 종합적으로 분석해줘 (기본정보, 스탯, 장비, 유니온)

"베라" 월드의 "우리길드" 길드원들의 레벨과 직업을 정리해줘

"스카니아" 월드와 "베라" 월드의 상위 랭커들을 비교 분석해줘

"내캐릭터" 캐릭터의 어제와 오늘 스탯 변화를 비교해줘

// 기본 캐릭터 정보 조회 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)

- --api-key- NEXON API 키
- --port- 서버 포트 (기본값: 3000)
- --debug- 디버그 로깅 활성화
- --name- 서버 이름 (기본값: "mcp-maple")
- --version- 서버 버전

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

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

- "새 애플리케이션 등록" 버튼 클릭
- 필수 정보 입력:

- 애플리케이션 이름:MCP Maple(예시)
- 애플리케이션 설명:Claude Desktop MCP 서버용
- 서비스 URL:http://localhost(개발용)

- 등록 완료 후 API 키 확인
- 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회 요청
- 데이터 갱신: 캐릭터 데이터는 매일 업데이트
- 캐시: 더 나은 성능을 위한 결과 캐싱
- 오류 처리: 일시적 실패에 대한 자동 재시도

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)

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

- characterName: 캐릭터 이름
- level: 캐릭터 레벨
- job: 캐릭터 직업/클래스
- world: 월드/서버 이름
- guildName: 길드 이름 (있는 경우)
- exp: 현재 경험치
- expRate: 경험치 비율 백분율

데미지, 크리티컬 확률, 모든 전투 스탯을 포함한 상세한 캐릭터 통계를 조회합니다.

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

- basicStats: STR, DEX, INT, LUK, HP, MP
- combatStats: 공격력, 마력, 크리티컬 스탯
- defenseStats: 물리/마법 방어 스탯
- allStats: 완전한 스탯 분석

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

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

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

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

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

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

증상: "API key is invalid" 또는 "Authentication failed" 오류
- NEXON 오픈 API 포털에서 API 키 상태 확인
- API 키가 만료되지 않았는지 확인
- 설정 파일에서 API 키가 올바르게 입력되었는지 확인
- API 키 앞뒤 공백 제거
- 캐릭터 이름을 정확히 입력 (대소문자, 특수문자 포함)
- 해당 캐릭터가 실제로 존재하는지 게임에서 확인
- 캐릭터가 최근에 생성된 경우 하루 정도 기다린 후 재시도
- 잠시 기다린 후 재시도 (1분 정도)
- 요청 빈도를 줄여서 사용
- 하루 500회 제한을 초과하지 않도록 주의

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

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

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

Interact with Alchemy's blockchain APIs to query data without writing code.