Quran

You can run a dedicated MCP server that communicates with the Quran.com API to fetch chapters, verses, Tafsirs, translations, and more. This server exposes a set of predefined endpoints as tools for MCP clients, letting you build powerful multilingual Quranic data flows with your preferred MCP client.

How to use

You connect to the Quran MCP server from your MCP client to perform actions like listing chapters, fetching verses by chapter or page, retrieving translations, and accessing Tafsirs and recitations. Use the available endpoints to query data, then integrate the results into your prompts and workflows. The server supports verbose logging to help you debug requests and responses.

How to install

Prerequisites: you need Node.js 22 or newer and Docker installed on your system.

1. Build the Docker image for production mode.

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

2. If you prefer running the server via Node.js in production mode, ensure you have built the project and then start with Node.js.

# Start in Node.js production mode (example)
node /path/to/quran-mcp-server/dist/src/server.js

3. For development mode, you can run the server with npx using ts-node to execute the TypeScript source directly.

# Development mode
npx ts-node /path/to/quran-mcp-server/src/server.ts

Note: replace "/path/to/quran-mcp-server" with the actual path to your local copy. If you are using the Docker production path, use the built image from step 1.

Additional setup and configuration

Environment variables control API access and logging. The following variables are recognized:

• API_KEY: API key for authentication with the Quran.com API if required.

• VERBOSE_MODE: Set to true to enable verbose logging of requests and responses.

• PORT: Server port to listen on (defaults may vary by language/runtime).

Testing

Run tests to ensure endpoints respond as expected.

npm test

End points and tools exposed

The server exposes endpoints from the Quran.com API as tools for MCP clients. You can query data such as chapters, verses, juzs, Hizb divisions, rub el hizb, specific verses, translations, tafsirs, audio reciters, and languages.

Notes on configuration and usage with Claude Desktop

If you use Claude Desktop, you can configure an MCP server entry to run either in Docker-based production mode, in Node.js production mode, or in development mode. Below are representative configurations you can adapt.

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

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

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

Available tools

get_chapters

List Chapters available in the Quran corpus.

get_chapter

Get a specific chapter by its id.

get_chapter_info

Get information about a specific chapter.

verses_by_chapter

Get verses by chapter (surah) number.

verses_by_page

Get all verses on a specific Madani Mushaf page.

verses_by_juz

Get verses by Juz number.

verses_by_hizb

Get verses by Hizb number.

verses_by_rub

Get verses by Rub el Hizb number.

verses_by_key

Get a verse by its key.

verses_random

Get a random verse.

list_juzs

Get a list of all juzs.

search_quran

Search the Quran for specific terms.

translations_list

Get list of available translations.

translation_info

Get information about a specific translation.

tafsirs_list

Get list of available tafsirs.

tafsir_info

Get information about a specific tafsir.

quran_tafsirs

Get a single tafsir.

chapter_reciters

List of Chapter Reciters.

recitation_styles

Get available recitation styles.

languages_list

Get all languages.