MapleStory MCP Server

MapleStory MCP Server 🍁

Un servidor integral del Protocolo de Contexto del Modelo (MCP) que permite acceder a los datos de la API abierta de NEXON MapleStory. Proporciona acceso estructurado a información de personajes, detalles de la Unión, datos de gremios, clasificaciones y mecánicas del juego a través de Claude Desktop y otros asistentes de IA compatibles con MCP.

✨ Características

• Información de personajes: Consulta detallada de estadísticas, equipo e información básica del personaje
• Sistema de Unión: Acceso a la composición y clasificaciones de la fuerza de ataque de la Unión
• Gestión de gremios: Consulta de información del gremio y detalles de los miembros
• Clasificaciones: Acceso a diversas tablas de clasificación y datos competitivos
• Mecánicas del juego: Información sobre probabilidades de mejora con cubos y Star Force
• Actualizaciones del juego: Últimos avisos y anuncios
• Soporte de TypeScript: Seguridad total de tipos y soporte de IntelliSense
• Registro integral: Registro detallado de operaciones para depuración
• Manejo de errores: Manejo robusto de errores con mensajes de error detallados

🚀 Inicio rápido

Uso con NPX (recomendado)

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

Instalación

npm install -g maplestory-mcp-server

🖥️ Uso con Claude Desktop

1. Preparación de la clave de API de NEXON

Primero, obtenga una clave de API en el Portal de API abierta de NEXON:

1. Inicie sesión con su cuenta de NEXON
2. Vaya a "Centro de desarrolladores" → "Gestión de aplicaciones"
3. Haga clic en "Registrar nueva aplicación"
4. Ingrese la información de la aplicación y regístrela
5. Copie la clave de API generada

2. Encontrar el archivo de configuración de Claude Desktop

Ubicación del archivo de configuración según el sistema operativo:

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

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

Linux:

~/.config/Claude/claude_desktop_config.json

3. Agregar la configuración del servidor MCP

Agregue o modifique el siguiente contenido en el archivo de configuración:

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

⚠️ Importante: Reemplace YOUR_NEXON_API_KEY con la clave de API real que haya obtenido.

4. Reiniciar Claude Desktop

Después de modificar el archivo de configuración, cierre completamente Claude Desktop y vuelva a iniciarlo.

5. Verificar la conexión

Una vez reiniciado Claude Desktop, verifique la conexión ingresando lo siguiente en una nueva conversación:

메이플스토리 API가 정상적으로 작동하는지 확인해줘

Si la conexión es exitosa, ¡Claude podrá responder preguntas relacionadas con MapleStory!

🛠️ Herramientas MCP disponibles

Herramientas de personaje

• get_character_basic_info - Consulta de información básica del personaje (nivel, clase, mundo, gremio)
• get_character_stats - Consulta de estadísticas detalladas del personaje y estadísticas de combate
• get_character_equipment - Consulta de equipo e ítems del personaje
• get_character_full_info - Consulta integral de información del personaje de una sola vez

Herramientas de Unión

• get_union_info - Consulta de nivel de Unión, grado e información de artefactos
• get_union_raider - Consulta de la composición del tablero de la fuerza de ataque de la Unión y bloques
• get_union_ranking - Consulta de clasificación de poder de la Unión

Herramientas de gremio

• get_guild_info - Consulta de información del gremio, miembros y habilidades
• get_guild_ranking - Consulta de clasificación por nivel de gremio

Herramientas de clasificación

• get_overall_ranking - Consulta integral de clasificación por nivel con opciones de filtro

Herramientas de utilidad

• get_notice_list - Consulta de avisos y anuncios del juego
• get_notice_detail - Consulta de información detallada de avisos
• get_cube_probability - Consulta de información de probabilidades de mejora con cubos
• get_starforce_probability - Consulta de información de probabilidades de mejora de Star Force
• health_check - Verificación de conexión y estado de la API

📖 Ejemplos de uso

🎯 Hacer preguntas en Claude Desktop

Puede consultar información de MapleStory en Claude Desktop usando lenguaje natural como el siguiente:

Consulta de información de personaje

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

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

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

Información de Unión y gremio

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

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

Consulta de clasificaciones

스카니아 월드의 아크메이지(불,독) 직업 랭킹 1페이지를 보여줘

베라 월드의 유니온 랭킹 상위 20명을 조회해줘

Información del juego

메이플스토리 최신 공지사항을 확인해줘

레드 큐브의 강화 확률 정보를 알려줘

💡 Consejos de uso

1. Análisis integral del personaje

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

2. Gestión de gremios

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

3. Comparación de clasificaciones

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

4. Seguimiento de progreso

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

🔧 Ejemplos de programación

Ejemplos de llamadas directas a la API para desarrolladores:

Consulta de información de personaje

// 기본 캐릭터 정보 조회
const basicInfo = await getCharacterBasicInfo({
  characterName: "스카니아용사"
});

// 상세한 캐릭터 스탯 조회
const stats = await getCharacterStats({
  characterName: "스카니아용사",
  date: "2024-01-15"
});

// 캐릭터 장비 조회
const equipment = await getCharacterEquipment({
  characterName: "스카니아용사"
});

Datos de Unión y gremio

// 유니온 정보 조회
const unionInfo = await getUnionInfo({
  characterName: "스카니아용사"
});

// 길드 정보 조회
const guildInfo = await getGuildInfo({
  guildName: "길드명",
  worldName: "스카니아"
});

Clasificaciones y tablas de líderes

// 종합 랭킹 조회
const rankings = await getOverallRanking({
  worldName: "스카니아",
  className: "아크메이지(불,독)",
  page: 1
});

// 유니온 랭킹 조회
const unionRankings = await getUnionRanking({
  worldName: "스카니아",
  page: 1
});

🔧 Configuración

Variables de entorno

• NEXON_API_KEY - Clave de API abierta de NEXON (obligatoria)
• LOG_LEVEL - Nivel de registro (valor predeterminado: "info")
• NODE_ENV - Entorno (development/production)

Opciones de CLI

• --api-key - Clave de API de NEXON
• --port - Puerto del servidor (valor predeterminado: 3000)
• --debug - Habilitar registro de depuración
• --name - Nombre del servidor (valor predeterminado: "mcp-maple")
• --version - Versión del servidor

🔑 Cómo obtener una clave de API de NEXON

Guía detallada

1. Acceda al Portal de API abierta de NEXON

   • Visite https://openapi.nexon.com/

2. Cree una cuenta e inicie sesión

   • Inicie sesión con su cuenta de NEXON (la misma que la cuenta del juego)
   • Si no tiene una cuenta, regístrese

3. Vaya al Centro de desarrolladores

   • Haga clic en "Centro de desarrolladores" en el menú superior
   • Seleccione "Gestión de aplicaciones"

4. Registre una nueva aplicación

   • Haga clic en el botón "Registrar nueva aplicación"
   • Ingrese la información obligatoria:
     • Nombre de la aplicación: MCP Maple (ejemplo)
     • Descripción de la aplicación: Claude Desktop MCP 서버용
     • URL del servicio: http://localhost (para desarrollo)

5. Obtenga y copie la clave de API

   • Después del registro, verifique la clave de API
   • Copie la clave de API (guárdela en un lugar seguro por seguridad)

6. Use la clave de API

   • En la configuración de Claude Desktop, úsela como NEXON_API_KEY
   • O en la CLI, úsela como parámetro --api-key

💡 Consejo: Tenga cuidado de no exponer su clave de API. No la suba a repositorios públicos como GitHub.

🎮 Juegos y mundos compatibles

Mundos de MapleStory

• Scania
• Bera
• Luna
• Zenith
• Croa
• Union
• Elysium
• Enosis
• Red
• Aurora
• Arcane
• Nova
• Reboot
• Reboot2

🚦 Límites de solicitudes y mejores prácticas

• Límite de solicitudes: 500 solicitudes por día por clave de API
• Frecuencia de solicitudes: Máximo 1 solicitud por segundo
• Actualización de datos: Los datos de personajes se actualizan diariamente
• Caché: Almacenamiento en caché de resultados para un mejor rendimiento
• Manejo de errores: Reintentos automáticos para fallos temporales

🧪 Desarrollo

Requisitos previos

• Node.js 18+
• TypeScript 5.4+
• Clave de API de NEXON

Configuración

git clone https://github.com/ljy9303/maplestory-mcp-server.git
cd maplestory-mcp-server
npm install
npm run build

Compilación

npm run build          # TypeScript 빌드
npm run dev            # 개발 모드 (watch)

📚 Referencia de la API

Herramientas de información de personaje

get_character_basic_info

Consulta información básica del personaje, incluidos nivel, clase, mundo y gremio.

Parámetros:

• characterName (string, obligatorio): Nombre del personaje a consultar
• date (string, opcional): Fecha en formato YYYY-MM-DD

Valores de retorno:

• characterName: Nombre del personaje
• level: Nivel del personaje
• job: Clase/ocupación del personaje
• world: Nombre del mundo/servidor
• guildName: Nombre del gremio (si existe)
• exp: Experiencia actual
• expRate: Porcentaje de experiencia

get_character_stats

Consulta estadísticas detalladas del personaje, incluidos daño, probabilidad crítica y todas las estadísticas de combate.

Parámetros:

• characterName (string, obligatorio): Nombre del personaje a consultar
• date (string, opcional): Fecha en formato YYYY-MM-DD

Valores de retorno:

• basicStats: STR, DEX, INT, LUK, HP, MP
• combatStats: Ataque, poder mágico, estadísticas críticas
• defenseStats: Estadísticas de defensa física/mágica
• allStats: Análisis completo de estadísticas

Herramientas de Unión

get_union_info

Consulta el nivel de Unión, grado e información de artefactos.

Parámetros:

• characterName (string, obligatorio): Nombre del personaje a consultar
• date (string, opcional): Fecha en formato YYYY-MM-DD

Valores de retorno:

• unionLevel: Nivel actual de Unión
• unionGrade: Grado/rango de Unión
• unionArtifact: Nivel y puntos de artefacto

Manejo de errores

Todas las herramientas devuelven información de error consistente:

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

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Lea la guía de contribución para más detalles.

Proceso de desarrollo

1. Haga un fork del repositorio
2. Cree una rama de funcionalidad
3. Realice los cambios
4. Agregue pruebas
5. Verifique que todas las pruebas pasen
6. Envíe una solicitud de extracción (pull request)

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulte el archivo LICENSE para más detalles.

🙏 Agradecimientos

• NEXON por proporcionar la API abierta de MapleStory
• Model Context Protocol por proporcionar la especificación de MCP
• Anthropic por proporcionar Claude y las herramientas de MCP

🔧 Solución de problemas

Problemas comunes

1. mcp-maple no se reconoce en Claude Desktop

Síntoma: Claude Desktop no puede responder preguntas relacionadas con MapleStory

Solución:

1. Cierre completamente Claude Desktop
2. Verifique que la ruta del archivo de configuración sea correcta:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
3. Verifique que el formato JSON sea correcto (comas, corchetes, etc.)
4. Reinicie Claude Desktop

2. Error de clave de API

Síntoma: Error "API key is invalid" o "Authentication failed"

Solución:

1. Verifique el estado de la clave de API en el Portal de API abierta de NEXON
2. Verifique que la clave de API no haya expirado
3. Verifique que la clave de API esté ingresada correctamente en el archivo de configuración
4. Elimine los espacios en blanco alrededor de la clave de API

3. No se encuentra el personaje

Síntoma: Error "Character not found"

Solución:

1. Ingrese el nombre del personaje con precisión (incluyendo mayúsculas, minúsculas y caracteres especiales)
2. Verifique en el juego que el personaje realmente exista
3. Si el personaje se creó recientemente, espere aproximadamente un día y vuelva a intentarlo

4. Límite de solicitudes excedido

Síntoma: Error "Rate limit exceeded"

Solución:

1. Espere un momento y vuelva a intentarlo (aproximadamente 1 minuto)
2. Reduzca la frecuencia de las solicitudes
3. Tenga cuidado de no exceder el límite de 500 solicitudes por día

5. Problemas de conexión de red

Síntoma: Error "Network error" o "Timeout"

Solución:

1. Verifique el estado de la conexión a Internet
2. Verifique la configuración del firewall o proxy
3. Vuelva a intentarlo después de un momento

Métodos de depuración

1. Ver registros detallados

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

2. Prueba de conexión

Ingrese lo siguiente en Claude Desktop para verificar el estado de la conexión:

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

3. Validación del archivo de configuración

Verifique que el formato JSON sea correcto con un validador JSON en línea.

Limitaciones conocidas

• Límite de llamadas a la API: 500 por día, 1 por segundo
• Actualización de datos: La información de personajes se actualiza alrededor de las 8 a. m. diariamente
• Mundos compatibles: Algunos servidores de prueba o mundos especiales pueden no ser compatibles

📞 Soporte

• Problemas: GitHub Issues
• Documentación: Referencia de la API
• Ejemplos: Ejemplos de uso

🔗 Proyectos relacionados

• MCP TypeScript SDK
• Claude Desktop
• NEXON Open API

---

Hecho con ❤️ para la comunidad de MapleStory