Gateway Service for Quranic Content Access

This Model Context Protocol (MCP) server bridges applications to the Quran.com knowledge base, utilizing the official Content API, Version 4.

System Synopsis

This service layer is instantiated directly from the OpenAPI specification file, mapping its definitions into callable tools for large language models.

Tool Exposure

The following specific resource interactions, derived from the underlying API, are exposed as functional tools for LLM utilization via compatible client machinery:

Scriptural Units (Chapters)

• Query all available Chapters: GET /chapters
• Fetch details for a specific Chapter: GET /chapters/{id}
• Retrieve supplementary metadata for a Chapter: GET /chapters/{chapter_id}/info

Individual Verses

• Retrieve verses partitioned by Chapter/Surah index: GET /verses/by_chapter/{chapter_number}
• Access verses corresponding to a specific page in the Madani Mushaf layout: GET /verses/by_page/{page_number}
• Fetch verses grouped by Juz (thirtieth part): GET /verses/by_juz/{juz_number}
• Fetch verses grouped by Hizb (half-Juz): GET /verses/by_hizb/{hizb_number}
• Fetch verses grouped by Rub el Hizb: GET /verses/by_rub/{rub_el_hizb_number}
• Obtain a verse using its unique locator key: GET /verses/by_key/{verse_key}
• Fetch an arbitrarily selected verse: GET /verses/random

Juz Index

• Enumerate all defined Juz sections: GET /juzs

Textual Search

• Execute full-text searches across the Quranic corpus: GET /search

Translations Index

• List all supported textual translations: GET /resources/translations
• Obtain descriptive data for a specified translation ID: GET /resources/translations/{translation_id}/info

Exegetical Commentaries (Tafsirs)

• List all accessible tafsir sources: GET /resources/tafsirs
• Retrieve metadata for a particular tafsir source: GET /resources/tafsirs/{tafsir_id}/info
• Fetch the complete content of a selected tafsir for a given context (implicit or explicit): GET /quran/tafsirs/{tafsir_id}

Auditory Resources

• Obtain the roster of available reciters for chapter-based audio playback: GET /resources/chapter_reciters
• List the recognized recitation styles: GET /resources/recitation_styles

Language Index

• Retrieve a comprehensive list of supported interface languages: GET /resources/languages

Deployment Prerequisites

System Requirements

• Runtime Environment: Node.js version 22 or newer
• Containerization Utility: Docker

Docker Image Construction

Prior to activating the containerized production deployment strategy, the necessary Docker artifact must be materialized:

bash

Construct the Docker artifact

docker build -t quran-mcp-server .

Integration with Claude Desktop

To enable seamless operation with Claude Desktop, incorporate the subsequent configuration block into your claude_desktop_config.json file (path typically found at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

Production Deployment via Containerization

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

Production Deployment (Native Node.js Execution)

{ "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 (Source Code Execution)

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

Crucial Directives: - Substitute /path/to/quran-mcp-server with the repository's absolute location on your filesystem. - Ensure the service is compiled via npm run build or the Docker image built if employing the production container configuration. - Insert a valid API credential into your_api_key_if_needed if the Quran.com endpoint mandates authorization. - If other MCP services are already defined, append this structure to the existing mcpServers map. - A restart of the Claude Desktop application is necessary for configuration updates to take effect.

Operational Parameters (Environment Variables)

• API_KEY: Authentication credential required for secure endpoint access.
• PORT: The network socket the service listens on (defaults vary, often 8000 or 3000).
• VERBOSE_MODE: Setting this to 'true' activates detailed logging of all transactions (default state is inactive).

Verbose Logging Functionality

When VERBOSE_MODE is activated, the server outputs comprehensive operational telemetry concerning interactions with the upstream API. This detail is invaluable for diagnostics and performance auditing.

The logging stream comprises:

• Invocation Logs: Records the designated tool name and its supplied arguments for every incoming request.
• Fulfillment Logs: Captures the tool name and the resulting payload upon successful response.
• Exception Logs: Details error conditions, including error identifiers, explanatory messages, and call stacks where obtainable.

Every entry in the log is time-stamped and tagged with its type (REQUEST, RESPONSE, or ERROR) for straightforward tracing.

Quality Assurance

bash

Execute verification suite

npm test

Licensing

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

---

(Note: The Wikipedia content regarding XMLHttpRequest (XHR) has been intentionally omitted as it is tangential to the MCP tool's functional description and setup guide.)