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 oficial v4 .

Descripción general

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

Related MCP server: Bible MCP

Puntos finales

Los siguientes puntos finales de la API se han puesto a disposición como herramientas que los LLM pueden utilizar a través de clientes compatibles.

Capítulos

• GET /chapters - Lista de capítulos

• GET /chapters/{id} - Obtener capítulo

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

Versos

• OBTENER /versos/por_capítulo/{número_de_capítulo} - Obtener versículos por capítulo/número de sura

• GET /verses/by_page/{page_number} - Obtener todos los versículos de una página específica de Madani Mushaf

• GET /verses/by_juz/{juz_number} - Obtener versos por número de Juz

• GET /verses/by_hizb/{hizb_number} - Obtener versículos por número de Hizb

• GET /verses/by_rub/{rub_el_hizb_number} - Obtener versos por número de Rub el Hizb

• GET /verses/by_key/{verse_key} - Obtener versículo por clave

• GET /versos/random - Obtener un versículo aleatorio

Jueces

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

Buscar

• OBTENER/buscar - Busque términos específicos en el Corán

Traducciones

• GET /resources/translations - Obtener una lista de traducciones disponibles

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

Tafsirs

• GET /resources/tafsirs - Obtener la lista de tafsirs disponibles

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

• GET /quran/tafsirs/{tafsir_id} - Obtén 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+

• Estibador

Construyendo la imagen de Docker

Antes de utilizar el modo de producción basado en Docker, debe crear la imagen de Docker:

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

Integración de escritorio de Claude

Para usar este servidor MCP con Claude Desktop, agregue la siguiente configuración a su 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:

• Reemplace /path/to/quran-mcp-server con la ruta real a este repositorio en su sistema

• Primero deberá compilar el proyecto con npm run build o docker build -t quran-mcp-server .

• Reemplace your_api_key_if_needed con una clave API real si lo requiere la API de Quran.com

• Si ya tiene otros servidores MCP configurados, agregue esta configuración al objeto mcpServers existente

• Después de actualizar la configuración, reinicie Claude Desktop para que los cambios surtan efecto.

Variables de entorno

• API_KEY : Clave API para autenticación

• PORT : Puerto del servidor (predeterminado: 8000 o 3000 según el idioma)

• VERBOSE_MODE : Establezca en 'verdadero' para habilitar el registro detallado de solicitudes y respuestas de API (valor predeterminado: falso)

Modo verboso

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 resulta útil para depurar y supervisar las interacciones de la API.

El registro detallado incluye:

• Solicitudes : registra el nombre de la herramienta y los argumentos para cada solicitud entrante

• Respuestas : registra el nombre de la herramienta y los datos del resultado de cada respuesta

• Errores : registra información detallada del error, incluido el nombre del error, el mensaje y el seguimiento de la pila cuando esté disponible

Cada entrada de registro tiene una marca de tiempo y un prefijo con el tipo de registro (SOLICITUD, RESPUESTA o ERROR) para una fácil identificación.

Pruebas

# Run tests
npm test

Licencia

Este proyecto está licenciado bajo la licencia MIT.