Quran.com API

Servidor MCP para la API de Quran.com

Servidor MCP para interactuar con el corpus de Quran.com a través de la API REST v4 oficial.

Descripción general

Este es un servidor de Protocolo de Contexto de Modelo (MCP) generado a partir de la especificación OpenAPI.

Endpoints

Los siguientes endpoints de la API se han puesto a disposición como herramientas que los LLM pueden usar mediante clientes compatibles.

Capítulos

• GET /chapters - Listar capítulos
• GET /chapters/{id} - Obtener capítulo
• GET /chapters/{chapter_id}/info - Obtener información del capítulo

Aleyas

• GET /verses/by_chapter/{chapter_number} - Obtener aleyas por número de capítulo / sura
• GET /verses/by_page/{page_number} - Obtener todas las aleyas de una página específica del Madani Mushaf
• GET /verses/by_juz/{juz_number} - Obtener aleyas por número de juz
• GET /verses/by_hizb/{hizb_number} - Obtener aleyas por número de hizb
• GET /verses/by_rub/{rub_el_hizb_number} - Obtener aleyas por número de rub el hizb
• GET /verses/by_key/{verse_key} - Obtener aleya por clave
• GET /verses/random - Obtener una aleya aleatoria

Juzes

• GET /juzs - Obtener la lista de todos los juzes

Búsqueda

• GET /search - Buscar términos específicos en el Corán

Traducciones

• GET /resources/translations - Obtener la lista de traducciones disponibles
• GET /resources/translations/{translation_id}/info - Obtener información de una traducción específica

Tafsires

• GET /resources/tafsirs - Obtener la lista de tafsires disponibles
• GET /resources/tafsirs/{tafsir_id}/info - Obtener la información de un tafsir específico
• GET /quran/tafsirs/{tafsir_id} - Obtener un solo tafsir

Audio

• GET /resources/chapter_reciters - Lista de recitadores de capítulos
• GET /resources/recitation_styles - Obtener los estilos de recitación disponibles

Idiomas

• GET /resources/languages - Obtener todos los idiomas

Configuración

Requisitos

• Node.js 22+
• Docker

Construcción de la imagen Docker

Antes de usar el modo de producción basado en Docker, debes construir la imagen Docker:

# Build the Docker image
docker build -t quran-mcp-server .

Integración con Claude Desktop

Para usar este servidor MCP con Claude Desktop, añade la siguiente configuración a tu archivo claude_desktop_config.json (normalmente ubicado en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS o %APPDATA%\Claude\claude_desktop_config.json en Windows):

Modo de producción basado en Docker

{
  "mcpServers": {
    "quran-api": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "-e", "API_KEY=your_api_key_if_needed", "-e", "VERBOSE_MODE=true", "quran-mcp-server"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Modo de producción (Node.js)

{
  "mcpServers": {
    "quran-api": {
      "command": "node",
      "args": ["/path/to/quran-mcp-server/dist/src/server.js"],
      "env": {
        "API_KEY": "your_api_key_if_needed",
        "VERBOSE_MODE": "true" // Set to "true" to enable verbose logging
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Modo de desarrollo

{
  "mcpServers": {
    "quran-api": {
      "command": "npx",
      "args": ["ts-node", "/path/to/quran-mcp-server/src/server.ts"],
      "env": {
        "API_KEY": "your_api_key_if_needed",
        "VERBOSE_MODE": "true" // Set to "true" to enable verbose logging
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Notas importantes:

• Reemplaza /path/to/quran-mcp-server con la ruta real de este repositorio en tu sistema
• Necesitarás construir el proyecto primero con npm run build o docker build -t quran-mcp-server . si usas la configuración del modo de producción
• Reemplaza your_api_key_if_needed con una clave de API real si la API de Quran.com lo requiere
• Si ya tienes otros servidores MCP configurados, añade esta configuración al objeto mcpServers existente
• Después de actualizar la configuración, reinicia Claude Desktop para que los cambios surtan efecto

Variables de entorno

• API_KEY: clave de API para autenticación
• PORT: puerto del servidor (predeterminado: 8000 o 3000 según el lenguaje)
• VERBOSE_MODE: establece en 'true' para habilitar el registro detallado de solicitudes y respuestas de la API (predeterminado: false)

Modo detallado

Cuando VERBOSE_MODE se establece en 'true', el servidor registrará información detallada sobre las solicitudes y respuestas de la API en la consola. Esto es útil para depurar y monitorear las interacciones con la API.

El registro detallado incluye:

• Solicitudes: registra el nombre de la herramienta y los argumentos de cada solicitud entrante
• Respuestas: registra el nombre de la herramienta y los datos de resultado de cada respuesta
• Errores: registra información detallada de errores, incluidos el nombre del error, el mensaje y el seguimiento de la pila cuando esté disponible

Cada entrada de registro lleva marca de tiempo y está prefijada con el tipo de registro (REQUEST, RESPONSE o ERROR) para facilitar su identificación.

Pruebas

# Run tests
npm test

Licencia

Este proyecto está licenciado bajo la Licencia MIT.