Quran

This MCP server connects your language model to a Quran API so you can fetch exact Quran passages on demand, reducing hallucinations while working with sacred text. It acts as a bridge, providing precise context only when you need it and keeping your prompts lean.

How to use

You use an MCP client to connect your language model to the local or remote MCP server. Start the server locally or remotely, then point your client to the server so it can request Quran passages as needed. The server handles requests to the Quran API and returns the exact data you specify, helping your model reference authentic text without embedding large chunks of content in every prompt.

How to install

Prerequisites: Python 3.13 and pip.

Clone the project, install dependencies, and start the server client.

git clone https://github.com/marwanWaly/quran_cloud_mcp_server.git
cd quran_cloud_mcp_server
python -m venv .venv
# Activate the virtual environment
# Windows
.\venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
pip install -r requirements.txt
# Create your environment file with your API key
OPENAI_API_KEY=Your-secret-key
# Run the client to start interacting
python client.py

Additional configuration and usage notes

You can connect the MCP server to Claude Desktop by configuring a local MCP server entry. The server is started with Python and the path to the server script is supplied to the editor. The following configuration enables Claude to communicate with the local server.

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

Notes on security and usage

Keep your OPENAI_API_KEY private and do not share the path to your local server in unsecured environments. When deploying, ensure the server is reachable only by trusted clients. Use HTTPS or secure tunneling if you expose the MCP server remotely.

Available tools

quran_api_access

Enables the MCP server to query the Quran API (https://alquran.cloud/api) and return exact passages to the client, reducing hallucinations when handling sacred text.