QuranDataAccessor_Service

An intermediary server component designed to grant Large Language Models (LLMs) controlled access to the AlQuran Cloud Application Programming Interface (API) (https://alquran.cloud/api). The primary objective is the complete prevention of inaccurate Quranic text generation.

Fabricated textual output presents a significant challenge, particularly when dealing with data where absolute character fidelity is non-negotiable, such as holy texts.

While supplying comprehensive context can reduce erroneous generation, pre-loading the entirety of a large corpus like the Holy Quran into every LLM query is computationally inefficient.

This repository introduces a specialized Mediator Control Point (MCP) server that interfaces your LLM with the publicly available API at https://alquran.cloud/api, empowering the model to dynamically fetch only the specific segments required.

Furthermore, comprehensive guidance is provided on configuring this MCP server to operate seamlessly with the Claude desktop application.

Initial Output Example (Unmodified Claude)

Enhanced Output Example (Post Search-Quran MCP Integration)

Deployment Instructions

Ensure Python version 3.13 or newer and pip are installed.

Execute the following sequence of shell commands:

Repository Cloning

git clone https://github.com/marwanWaly/quran_cloud_mcp_server.git

Directory Navigation

cd quran_cloud_mcp_server

Virtual Environment Creation

python -m venv .venv

Environment Activation

Windows:

.\venv\Scripts\activate

macOS or Linux:

source .venv/bin/activate

Dependency Resolution

Install necessary libraries listed in requirements.txt using the pip package manager.

pip install -r requirements.txt

Environment Configuration File Setup

Create a file named .env with your key information:

OPENAI_API_KEY=Your-secret-key

Server Execution

Initiate the service via the terminal:

python client.py

You are now equipped to interact with GPT4o functionalities directly from your console.

Integrating with Claude Desktop Client

Acquire and launch the Claude desktop application.

Configuration Step 1

Navigate to the application's settings menu, accessible via the 'File' menu.

Configuration Step 2

Select the 'Developer' tab and choose 'Edit Config'.

Configuration Step 3

Locate and open the configuration file named claude_desktop_config.json.

Configuration Step 4

Insert the following JSON structure into the file:

{ "mcpServers": { "Search-Quran": { "command": "python", "args": [ "PROJECT_PATH_ON_YOUR_PC\server.py" ], "host": "127.0.0.1", "port": 8080, "timeout": 30000 } } }

Crucially, substitute PROJECT_PATH_ON_YOUR_PC with the absolute directory path pointing to your server script.

Configuration Step 5

Perform a full restart of the Claude application (ensure it is fully quit from the system tray). Verify that the new MCP entry, "Search-Quran," is registered in the configuration interface.

Access the integrated tools via the tool icon: