Empowering LLMs with Quranic Knowledge: An MCP Server for Quran.com API

Unlock the potential of Large Language Models (LLMs) by connecting them to the rich textual and audio resources of the Quran. This document details the implementation of a Model Context Protocol (MCP) server that acts as a bridge between LLMs and the official Quran.com REST API v4. By leveraging this server, developers can create AI applications capable of understanding, interpreting, and interacting with the Quran in profound ways.

Core Functionality: Exposing Quran.com API as LLM Tools

This MCP server transforms key endpoints from the Quran.com API into accessible tools for LLMs. This allows AI agents to dynamically retrieve and utilize Quranic data within their reasoning and generation processes. The following endpoints are exposed:

Chapter Management

GET /chapters: Retrieve a comprehensive list of all chapters (Surahs) in the Quran.
GET /chapters/{id}: Obtain detailed information about a specific chapter using its unique identifier.
GET /chapters/{chapter_id}/info: Access supplementary information about a chapter, such as its classification (Meccan or Medinan) and thematic overview.

Verse Retrieval

GET /verses/by_chapter/{chapter_number}: Fetch all verses belonging to a specific chapter (Surah).
GET /verses/by_page/{page_number}: Retrieve all verses found on a particular page of the Madani Mushaf.
GET /verses/by_juz/{juz_number}: Access all verses within a specific Juz' (a section of the Quran).
GET /verses/by_hizb/{hizb_number}: Retrieve verses within a specific Hizb (half of a Juz').
GET /verses/by_rub/{rub_el_hizb_number}: Access verses within a specific Rub' el Hizb (quarter of a Hizb).
GET /verses/by_key/{verse_key}: Obtain a specific verse using its unique key (e.g., "2:255" for verse 255 of Surah Al-Baqarah).
GET /verses/random: Retrieve a randomly selected verse from the Quran.

Quranic Structure

GET /juzs: Obtain a list of all Juz's (sections) of the Quran.

Semantic Search

GET /search: Perform keyword-based searches within the Quranic text.

Linguistic Resources

GET /resources/translations: Retrieve a list of available translations of the Quran in various languages.
GET /resources/translations/{translation_id}/info: Access detailed information about a specific translation, including the translator and language.

Exegetical Resources (Tafsir)

GET /resources/tafsirs: Retrieve a list of available Tafsirs (interpretations/commentaries) of the Quran.
GET /resources/tafsirs/{tafsir_id}/info: Access detailed information about a specific Tafsir, including the author and methodology.
GET /quran/tafsirs/{tafsir_id}: Retrieve the full text of a specific Tafsir.

Auditory Resources

GET /resources/chapter_reciters: Retrieve a list of available reciters for each chapter of the Quran.
GET /resources/recitation_styles: Get the available recitation styles.

Language Information

GET /resources/languages: Retrieve a list of all languages supported by the Quran.com API.

Deployment and Integration

This MCP server can be deployed in various environments, offering flexibility for different development and production needs.

Prerequisites

Node.js 22+: Ensure you have a compatible version of Node.js installed.
Docker: Docker is required for the containerized deployment option.

Docker-Based Deployment

Build the Docker Image:
```
docker build -t quran-mcp-server .
```

Configure Claude Desktop (or other MCP Client):

Add the following configuration to your claude_desktop_config.json file:

{
  "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": []
    }
  }
}

Node.js Deployment

Install Dependencies:
```
npm install
```
Build the Project:
```
npm run build
```

Configure Claude Desktop (or other MCP Client):

{
  "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"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Development Mode

For rapid development and testing, use the following configuration:

{
  "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"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Important Considerations:

Replace /path/to/quran-mcp-server with the actual path to the repository.
Replace your_api_key_if_needed with your Quran.com API key if required.
Restart Claude Desktop (or your MCP client) after modifying the configuration.

Environment Configuration

The server's behavior can be customized using environment variables:

API_KEY: API key for authenticating with the Quran.com API (if required).
PORT: The port on which the server will listen for incoming requests (defaults to 8000 or 3000).
VERBOSE_MODE: Set to true to enable detailed logging of API requests and responses for debugging purposes (defaults to false).

Enhanced Debugging with Verbose Mode

Enabling VERBOSE_MODE provides invaluable insights into the server's operation. When activated, the server logs:

Incoming Requests: The tool name and arguments associated with each request received from the LLM.
Outgoing Responses: The tool name and the data returned by the Quran.com API.
Errors: Detailed error information, including the error name, message, and stack trace, facilitating rapid troubleshooting.

Each log entry is timestamped and clearly labeled (REQUEST, RESPONSE, or ERROR) for easy analysis.

Testing and Validation

Ensure the server is functioning correctly by running the provided tests:

npm test

Conclusion

This MCP server provides a powerful and standardized interface for connecting LLMs to the vast resources of the Quran.com API. By leveraging this server, developers can create innovative AI applications that promote understanding, exploration, and engagement with the Quranic text.

quran-mcp-server