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 .

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.

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

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