Skip to main content
Glama
quran-mcp-server

quran-mcp-server

by djalal

MCP Server for Quran.com API

MCP server to interact with Quran.com corpus via the official REST API v4.

Overview

This is a Model Context Protocol (MCP) server generated from the OpenAPI specification.

Related MCP server: Wasilah MCP

Endpoints

The following endpoints from the API have been made available as tools, that LLMs can use via compatible clients.

Chapters

  • GET /chapters - List Chapters

  • GET /chapters/{id} - Get Chapter

  • GET /chapters/{chapter_id}/info - Get Chapter Info

Verses

  • GET /verses/by_chapter/{chapter_number} - Get verses by Chapter / Surah number

  • GET /verses/by_page/{page_number} - Get all verses of 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 verse by key

  • GET /verses/random - Get a random verse

Juzs

  • GET /juzs - Get list of all juzs

  • GET /search - Search the Quran for specific terms

Translations

  • GET /resources/translations - Get list of available translations

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

Tafsirs

  • GET /resources/tafsirs - Get list of available tafsirs

  • GET /resources/tafsirs/{tafsir_id}/info - Get the information of a specific tafsir

  • GET /quran/tafsirs/{tafsir_id} - Get a single tafsir

Audio

  • GET /resources/chapter_reciters - List of Chapter Reciters

  • GET /resources/recitation_styles - Get the available recitation styles

Languages

  • GET /resources/languages - Get all languages

Setup

Requirements

  • Node.js 22+

  • Docker

Building the Docker Image

Before using the Docker-based production mode, you need to build the Docker image:

# Build the Docker image
docker build -t quran-mcp-server .

Claude Desktop Integration

To use this MCP server with Claude Desktop, add the following configuration to your claude_desktop_config.json file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

Docker-based Production Mode

{
  "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 Mode (Node.js)

{
  "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" // Set to "true" to enable verbose logging
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Development Mode

{
  "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" // Set to "true" to enable verbose logging
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Important Notes:

  • Replace /path/to/quran-mcp-server with the actual path to this repository on your system

  • You'll need to build the project first with npm run build or docker build -t quran-mcp-server . if using the production mode configuration

  • Replace your_api_key_if_needed with an actual API key if required by the Quran.com API

  • If you already have other MCP servers configured, add this configuration to the existing mcpServers object

  • After updating the configuration, restart Claude Desktop for the changes to take effect

Environment Variables

  • API_KEY: API key for authentication

  • PORT: Server port (default: 8000 or 3000 depending on language)

  • VERBOSE_MODE: Set to 'true' to enable verbose logging of API requests and responses (default: false)

Verbose Mode

When VERBOSE_MODE is set to 'true', the server will log detailed information about API requests and responses to the console. This is useful for debugging and monitoring API interactions.

The verbose logging includes:

  • Requests: Logs the tool name and arguments for each incoming request

  • Responses: Logs the tool name and result data for each response

  • Errors: Logs detailed error information including error name, message, and stack trace when available

Each log entry is timestamped and prefixed with the log type (REQUEST, RESPONSE, or ERROR) for easy identification.

Testing

# Run tests
npm test

License

This project is licensed under the MIT License.

Available Tools

20 tools
chapter-recitersC

List of Chapter Reciters

Inputs: language.

GET-chapterD

Get Chapter

Inputs: language (required), id.

infoC

Get Chapter Info

Inputs: language (required), chapter_id.

juzsB

Get list of all juzs

Inputs: no named parameters.

languagesC

Get all languages

Inputs: language.

list-chaptersD

List Chapters

Inputs: language (required).

random_verseC

Get a random verse

Inputs: audio, fields, language, tafsirs, +4 more.

recitation-stylesB

Get the available recitation styles

Inputs: no named parameters.

tafsirC

Get a single tafsir

Inputs: tafsir_id (required), chapter_number, fields, hizb_number, +4 more.

tafsir-infoC

Get the information of a specific tafsir

Inputs: tafsir_id (required).

tafsirsC

Get list of available tafsirs

Inputs: language.

translation-infoC

Get information of a specific translation

Inputs: translation_id (required).

translationsC

Get list of available translations

Inputs: language.

verses-by_chapter_numberC

Get verses by Chapter / Surah number

Inputs: chapter_number (required), audio, fields, language, +7 more.

verses-by_hizb_numberC

Get verses by Hizb number

Inputs: hizb_number (required), audio, fields, language, +7 more.

verses-by_juz_numberC

Get verses by Juz number

Inputs: juz_number (required), audio, fields, language, +7 more.

verses-by_page_numberB

Get all verses of a specific Madani Mushaf page

Inputs: page_number (required), audio, fields, language, +7 more.

verses-by_rub_el_hizb_numberB

Get verses by Rub el Hizb number

Inputs: rub_el_hizb_number (required), audio, fields, language, +5 more.

verses-by_verse_keyC

Get verse by key

Inputs: verse_key (required), audio, fields, language, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 20 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap between 'GET-chapter', 'info', and 'list-chapters' that could cause confusion, as they all relate to chapter information. The verses retrieval tools are well-differentiated by their indexing methods (e.g., chapter number, juz number).

    Naming Consistency2/5

    Naming is inconsistent with mixed conventions: some use snake_case (e.g., 'random_verse'), some use kebab-case (e.g., 'chapter-reciters'), some use camelCase (e.g., 'verses-by_chapter_number'), and one uses uppercase prefix ('GET-chapter'). There is no uniform verb_noun pattern, making it harder to predict tool names.

    Tool Count3/5

    With 20 tools, the count is borderline high for a Quran-focused server, but it covers various aspects like chapters, verses, recitations, tafsirs, and translations. It feels slightly heavy but still manageable given the domain's complexity.

    Completeness5/5

    The tool set provides comprehensive coverage for accessing Quranic content, including chapters, verses by multiple indices, recitations, translations, tafsirs, and search functionality. There are no obvious gaps for typical agent workflows in this domain.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server to search and retrieve passages from a corpus of 7,872 classical Islamic books via the Sahifah API, with full citations and mu'tabar filtering.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Remote MCP server exposing Wasilah's Islamic reference data, enabling prayer-time, Qibla, Hijri-date, and Quran-audio queries via natural language.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI clients with fast, hallucination-free access to the Quran through 13 MCP tools, covering search, navigation, morphology, tafsir, translations, and surah background over stdio and Streamable HTTP.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Serves a scholar-approved Islamic corpus of Qur'an and hadith passages to any MCP client with server-side refusal enforcement. Enables natural-language questioning, retrieval, policy checking, and honest corpus coverage reporting while preventing fabricated answers.
      6
      MIT