Quran MCP Server

🚀 Quran.com API's MCP Server

This is an MCP server that interacts with Quran.com text through the official REST API v4. It provides a seamless way to access various Quran-related data.

🚀 Quick Start

Environment Variables

• API_KEY: API key for authentication.
• PORT: Server port (Default: 8000 or 3000, depending on the language).
• VERBOSE_MODE: Set to 'true' to enable verbose logging mode (Default: false).

Configuration Examples

Using bash:

export API_KEY="your_api_key_here"
export PORT=8000
export VERBOSE_MODE=true

Using PowerShell (Windows):

$env:API_KEY = "your_api_key_here"
$env:PORT = 8000
$env:VERBOSE_MODE = "true"

Configuration in Claude Desktop

Add the following content to the claudius.json configuration file:

{
  "mcpServers": {
    "quranComMCP": {
      "type": "custom",
      "executablePath": "/path/to/node/bin/npm",
      "scriptName": "start",
      "args": [
        "--port",
        "8000",
        "--api-key",
        "your_api_key_here"
      ],
      "environmentVariables": {
        "VERBOSE_MODE": "true"
      }
    }
  }
}

✨ Features

Overview

This MCP server is generated from the OpenAPI specification (v4.json).

Endpoints

The following API endpoints are provided as tools, which can be used by LLMs through compatible clients:

Chapters

• GET /chapters - List chapters.
• GET /chapters/{id} - Get a chapter.
• GET /chapters/{chapter_id}/info - Get chapter information.

Verses

• GET /verses/by_chapter/{chapter_number} - Get verses by chapter/surah number.
• GET /verses/by_page/{page_number} - Get all verses on a specific Madani Mushaf page.
• GET /verses/by_juz/{juz_number} - Get verses by Juz number.
• GET /verses/by_hizb/{hizb_number} - Get verses by Hizb number.
• GET /verses/by_rub/{rub_el_hizb_number} - Get verses by Rub el Hizb number.
• GET /verses/by_key/{verse_key} - Get a verse by key.
• GET /verses/random - Get a random verse.

Juzs

• GET /juzs - Get a list of all Juzs.

Search

• GET /search - Search for specific terms in the Quran.

Translations

• GET /resources/translations - Get a list of available translations.
• GET /resources/translations/{translation_id}/info - Get information about a specific translation.

Verbose Logging Mode

When VERBOSE_MODE is set to 'true', the server outputs detailed API request and response logs in the console. This is very useful for debugging and monitoring API interactions.

Detailed logs include:

• Request: Records the tool name and parameters of each incoming request.
• Response: Records the result data and tool name of each response.
• Error: Records error information, including error name, message, and stack trace (if available).

Each log is timestamped and preceded by an identifier (e.g., REQUEST, RESPONSE, or ERROR) for easy identification.

Complete Log Example

When VERBOSE_MODE is enabled, the console output might look like this:

[2023-10-01 12:34:56] REQUEST - GET /verses/random 
[2023-10-01 12:34:57] RESPONSE - {
  "chapter": {
    "number": 1,
    "name": "Al-Fatiha",
    "translation": "The Opening"
  },
  "verse": {
    "number": 1,
    "text": "In the name of Allah, Most Gracious, Most Merciful..."
  }
}
[2023-10-01 12:35:01] ERROR - An error occurred while fetching the verse: Network connection interrupted

📦 Installation

No specific installation steps are provided in the original document.

💻 Usage Examples

Testing

# Run tests
npm test

📚 Documentation

Complete Environment Variable Explanation

• API_KEY: Required. Used for authentication with the Quran.com API.
• PORT: Optional, default value is 8000 or 3000 (depending on the language). Specifies the port on which the server listens.
• VERBOSE_MODE: Optional, default value is 'false'. Enables verbose logging mode to record all API requests and responses.

Configuration in Claude Desktop

1. Open the claudius.json configuration file (usually located in the user's home directory).
2. Add the following content to the mcpServers object:

{
  "quranComMCP": {
    "type": "custom",
    "executablePath": "/path/to/node/bin/npm",  // Fill in according to the actual Node.js installation path
    "scriptName": "start",
    "args": [
      "--port",
      "8000",
      "--api-key",
      "your_api_key_here"
    ],
    "environmentVariables": {
      "VERBOSE_MODE": "true"  // Enable verbose logging mode
    }
  }
}

3. Adjust the executablePath according to the actual path.
4. Replace your_api_key_here with the actual API key.
5. Save the file and restart Claude Desktop for the configuration to take effect.

📄 License

This project is licensed under the MIT License.