Textual Access Nexus for the Holy Scripture Corpus

This Model Context Protocol (MCP) engine is engineered to interface precisely with the Quran.com data repository, leveraging its formal REST API specification, version 4.

High-Level Summary

This utility acts as an abstraction layer, translating LLM directives into structured calls against the OpenAPI document that defines the Quran.com content service. It exposes curated endpoints as discrete, actionable tools for compatible client applications.

Available Functional Interfaces (Endpoints)

The following capabilities, derived directly from the underlying API, are exposed for algorithmic utilization:

Scriptural Divisions (Chapters/Surahs)

• Fetching a complete roster of all divisions (GET /chapters)
• Retrieving specific data for an identified division (GET /chapters/{id})
• Obtaining supplementary metadata for a given chapter (GET /chapters/{chapter_id}/info)

Individual Passages (Verses)

• Querying passages based on their primary division number (GET /verses/by_chapter/{chapter_number})
• Locating verses corresponding to a specific page in the Madani print standard (GET /verses/by_page/{page_number})
• Retrieving verses segmented by the traditional thirty Juz parts (GET /verses/by_juz/{juz_number})
• Accessing verses grouped by Hizb markers (GET /verses/by_hizb/{hizb_number})
• Fetching passages delimited by the Rub el Hizb sections (GET /verses/by_rub/{rub_el_hizb_number})
• Resolving a passage using its unique identifier key (GET /verses/by_key/{verse_key})
• Requesting a randomly selected passage (GET /verses/random)

Juz Segmentation Index

• Listing all thirty Juz divisions (GET /juzs)

Content Search Mechanism

• Executing keyword searches across the Quranic text base (GET /search)

Interpretive and Linguistic Resources (Translations)

• Obtaining a directory of available translated texts (GET /resources/translations)
• Fetching metadata for a selected translation variant (GET /resources/translations/{translation_id}/info)

Scholarly Commentaries (Tafsirs)

• Retrieving the catalog of available exegeses (GET /resources/tafsirs)
• Fetching descriptive metadata for a specified exegesis (GET /resources/tafsirs/{tafsir_id}/info)
• Retrieving the full text of a single commentary entry (GET /quran/tafsirs/{tafsir_id})

Recitation Assets (Audio)

• Listing available reciters for chapter audio playback (GET /resources/chapter_reciters)
• Identifying supported modes of recitation (GET /resources/recitation_styles)

Lexical Support

• Retrieving the list of supported human languages (GET /resources/languages)

Deployment Protocols

Prerequisites

• Execution environment must feature Node.js version 22 or newer.
• Docker utility is required for containerized deployment.

Container Image Construction

To ready the service for execution within a Docker context, execute the following command to build the necessary artifact:

bash

Construct the Docker artifact

docker build -t quran-mcp-server .

Integration into Claude Desktop Interface

To enable interaction with this textual utility via Claude Desktop, integrate the corresponding configuration block into your claude_desktop_config.json file (location varies by OS, e.g., ~/Library/Application Support/Claude/... on macOS):

Containerized Production Setup

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

Direct Node.js Production Runtime

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

Active Development Mode (Source Files)

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

Critical Implementation Directives: - Substitute /path/to/quran-mcp-server with the definitive directory path on your local filesystem. - Ensure prerequisite compilation (npm run build or the docker build command) is executed prior to utilizing production configurations. - Update your_api_key_if_needed with valid credentials if the Quran.com service mandates authorization. - Configuration merging: Append this server definition to any existing entries within the mcpServers object. - A full relaunch of the Claude Desktop application is required for configuration updates to become active.

Operational Parameters (Environment Variables)

• API_KEY: Credential required for authenticated access to the upstream API.
• PORT: The network conduit the server listens on (defaults are typically 8000 or 3000 depending on the runtime environment).
• VERBOSE_MODE: Setting this to 'true' activates extensive logging of all inbound requests and outbound responses (default status is 'false').

Diagnostic Logging (Verbose Mode)

When VERBOSE_MODE is activated, the service outputs comprehensive diagnostic data, invaluable for troubleshooting and monitoring API transactional integrity. The logging structure incorporates a precise timestamp and a log classification prefix (REQUEST, RESPONSE, or ERROR) for clear traceability:

• Inbound Requests: Logs the invocation name of the tool and its associated input parameters.
• Outbound Responses: Records the tool name that was executed and the resultant data payload.
• Fault Reporting: Captures detailed error context, including exception class, descriptive message, and stack trace information where available.

Verification Suite

bash

Initiate the automated test suite

npm test

Project Endowment License

This software utility is released under the terms of the MIT License.

CULTURAL_CONTEXT_NOTE: The concept of popular culture (often contrasted with 'high culture' or 'folk culture') describes the prevailing, widely disseminated collection of beliefs, artistic creations, and societal practices dominant within a contemporary milieu. Historically, mass media and capitalist imperatives have fueled its expansion, influencing everyday perceptions. This tool, conversely, deals with a singular, foundational religious text, often regarded as immutable or possessing a cultural status distinct from the transient nature of typical popular output.