LABSCO SUMMARY

The Quran.com API, already shaped for a conversation.

Nothing here is invented — it is the official v4 REST API turned into tools, which means the assistant can answer "what does this tafsir say about that verse" by making the two calls itself instead of asking you for an endpoint.

What it is

An MCP server generated from the Quran.com REST API v4 OpenAPI specification. Each covered endpoint becomes a tool, so an assistant can pull chapters, verses, translations, tafsirs and audio resources directly.

What you get

Chapters: the full list, a single chapter, and its background info
Verses fetched the way you actually refer to them — by chapter, by Madani Mushaf page, by juz, by hizb, by rub el hizb, by verse key, or at random
Full-text search across the corpus
The catalogue of available translations and tafsirs, the details of any one of them, and a single tafsir retrieved in full
Audio resources: chapter reciters and the available recitation styles
The list of juzs, and the list of supported languages

Requirements

Node.js 22+, and Docker if you take the container path — build the image with docker build -t quran-mcp-server ., or build the project and run dist/src/server.js with Node. API_KEY is passed through for the Quran.com API when one is needed, and VERBOSE_MODE=true logs every request, response and error with a timestamp. MIT.

Setup effort

Run a container — build the image from the repository, then point your client at it

See installation options

USE CASES

01

Looking up a passage by any reference you happen to have

Chapter and verse, a Mushaf page number, a juz or a hizb all resolve to the same verses, so you do not have to convert between systems first.

02

Comparing how a verse was translated

List the available translations, read the details of the ones you care about, then pull the verse under each.

03

Reading commentary alongside the text

Find which tafsirs exist, check what a given one is, and retrieve it in full next to the verses it covers.

04

Finding where a phrase appears

Search the corpus for a term and follow the hits back to their chapters.

05

Picking a recitation to listen to

List chapter reciters and the recitation styles they use before choosing an audio source.

BEFORE YOU INSTALL

What to know first

Requires

docker on PATH
Node.js 22+

Where it runs

All 3 documented setups run the server on your machine.

INSTALLATION

Connect your client

Build the image from the repository, then point your client at it.

Server setup

TERMINAL

git clone https://github.com/djalal/quran-mcp-server.git
cd quran-mcp-server
docker build -t quran-mcp-server .

Or, for the Node.js configurations: npm install, then npm run build

MCP Clients

Claude Desktop — Docker

CLAUDE DESKTOP — DOCKER · JSON

{
  "mcpServers": {
    "quran-api": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e",
        "API_KEY=<YOUR_API_KEY>",
        "-e",
        "VERBOSE_MODE=true",
        "quran-mcp-server"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Claude Desktop — Node.js

CLAUDE DESKTOP — NODE.JS · JSON

{
  "mcpServers": {
    "quran-api": {
      "command": "node",
      "args": [
        "<YOUR_PATH_TO_QURAN_MCP_SERVER>/dist/src/server.js"
      ],
      "env": {
        "API_KEY": "<YOUR_API_KEY>",
        "VERBOSE_MODE": "true"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

<YOUR_PATH_TO_QURAN_MCP_SERVER> is the folder git clone created; build it first with npm install and npm run build.

Claude Desktop — ts-node

CLAUDE DESKTOP — TS-NODE · JSON

{
  "mcpServers": {
    "quran-api": {
      "command": "npx",
      "args": [
        "ts-node",
        "<YOUR_PATH_TO_QURAN_MCP_SERVER>/src/server.ts"
      ],
      "env": {
        "API_KEY": "<YOUR_API_KEY>",
        "VERBOSE_MODE": "true"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

<YOUR_PATH_TO_QURAN_MCP_SERVER> is the folder git clone created, after npm install there.

Quran.com API