Which MCP hosts does the Madeenan server work with?

Any MCP host that can start a local stdio server. The included config uses the mcpServers format from Claude Desktop and Cursor. VS Code uses a servers block, and Claude Code adds servers with claude mcp add.

Do I need an API key?

Not for the current source tools. Without a key, requests use the public service limits. Set MADEENAN_API_KEY in the host's server environment for plan limits. Never paste the key into a chat or tool argument.

Is there a hosted Quran MCP endpoint?

No. Madeenan does not run a public MCP endpoint. Run the server locally over stdio, or self-host Streamable HTTP behind an authenticated gateway.

Can the server answer religious questions or give fatwas?

No. It retrieves sources and prepares evidence for review. The assistant's reply is still model output, and interpretation belongs with qualified scholars.

Is the server on PyPI?

Not yet. The package is prepared for PyPI. Until it is published, setup needs a copy of the Madeenan repository, as the MCP setup docs describe.

MCP Server

Quran MCP Server With Hadith, Tafsir, and Dua Sources

Give an AI assistant tools to search Quran, Hadith, Tafsir, and dua sources, read exact references, check where a quote appears, and collect evidence for review. The server is read-only and runs locally over stdio.

Read the MCP Setup View API Plans

Tools: 7 read-only tools, one status resource, and one review prompt
Sources: Quran, six Hadith collections, five Tafsir editions, and Hisn al-Muslim duas
Transport: stdio for local hosts; Streamable HTTP for a self-hosted deployment
API Key: Optional for the current tools. Set it in the host's environment, never as a tool argument.

Sources, Not Answers

The server gives the model sources to read. It does not generate answers on its own and does not expose hosted chat. The assistant still writes the reply, but now it can cite a verse or report it actually retrieved.

Every tool returns the reference and source fields, so you can ask the assistant to quote the reference and check it yourself.

More Than the Qur'an

Most Quran MCP servers cover the Qur'an and its commentary. This one also searches six Hadith collections with grade metadata, Hisn al-Muslim duas, and quote wording. That helps when a question crosses source types, such as 'what do the Qur'an and Sunnah say about patience?'

Evidence for Review, Not Rulings

create_evidence_bundle gathers search results and requested references into one place. review_evidence_claim returns a checklist marked needs_human_review. Neither tool decides whether a claim is true, and neither issues a fatwa. Religious interpretation belongs with qualified scholars.

Local First, With a Clear Security Boundary

Run the server over stdio on your own machine. The API key is read from the server's environment and is never returned in tool output, errors, or logs.

Streamable HTTP is available for self-hosting, but the server has no inbound client authentication. Put it behind a gateway that enforces authentication and TLS before anyone outside your machine can reach it.

Tools

search_islamic_sources: Search Quran, Hadith, Tafsir, and dua sources. Accepts indexes, a result limit from 1 to 25, and an optional Hadith grade filter.
lookup_quran_reference: Read one verse (2:255), a chapter (2), or a bounded passage of up to 50 ayahs.
lookup_hadith_reference: Read one Hadith by collection slug and number, with its grade metadata.
lookup_dua: Read one dua or adhkar item by collection slug and item ID.
find_quote_source: Find wording matches for a quote. A match does not prove authorship or meaning.
create_evidence_bundle: Collect search results and up to eight Quran references into one bundle for review.
review_evidence_claim: Return an evidence checklist marked for human review. It does not verify a claim or issue a ruling.

The server also provides a config://status resource, which reports safe settings without the key, and a source_review_prompt prompt.

Setup

Install and Check Settings

Python 3.11 or newer. The configuration check runs offline and never prints the key.

$# From the Madeenan repository root:

python -m venv .venv-mcp

.venv-mcp/bin/python -m pip install ./packages/python ./apps/mcp

# Check settings offline. This does not check your key with the API.

.venv-mcp/bin/madeenan-mcp --check-config

# Print a stdio configuration with an absolute executable path.

.venv-mcp/bin/madeenan-mcp --print-config

Add It to an MCP Host

This is the mcpServers format used by Claude Desktop and Cursor. Merge it with your existing servers. VS Code and Claude Code use their own formats.

{

"mcpServers": {

"madeenan": {

"command": "/absolute/path/to/.venv-mcp/bin/madeenan-mcp",

"args": ["--transport", "stdio"]

}

What It Does Not Do

Not on PyPI yet. Setup currently needs a copy of the Madeenan repository, as described in the MCP setup docs.
No public hosted endpoint. You run the server yourself.
Read-only. There are no chat, write, or account tools.
One English Quran translation and no word-level morphology.

How It Compares

Several Quran MCP servers now exist. They overlap, but each is built around a different source set. This comparison is based on each project's public README.

Need	Madeenan	quran/quran-mcp (Quran.com)	Other Community Quran Servers
Built For	Cross-source research: Quran, Hadith, Tafsir, and duas	Deep Quran study with Quran.com content	Varies; most wrap a single Quran API
Quran Translations	One English translation	50+ translations in 30+ languages	Depends on the API they wrap
Tafsir	Five editions in Arabic and English	Commentary from 15+ scholars	Varies
Hadith	Six collections with grade metadata	Not listed	Usually separate servers
Duas and Quote Matching	Yes	Not listed	Varies
Morphology	Not offered	Word-level morphology and roots	Some projects
Hosting	Local stdio or self-hosted HTTP	Hosted endpoint or self-hosted Docker	Varies

If you only need Quran text, translations, and tafsir inside an assistant, Quran.com's server covers more of them than Madeenan does. Madeenan fits when the same question needs Hadith, duas, or quote checking too. Checked in October 2026.

Sources: quran/quran-mcp on GitHub

Plans and Limits

The MCP tools call the same API. Without a key they use the free public limits; with a key they use your plan's limits.

Free

$0 per month

10 searches/day
No hosted chat
No API key access
Source search for evaluation

Starter

$5 per month

3,000 searches/month
API key access
Source retrieval and citation payloads
100 hosted chat answers/month
60 requests per minute per key

API / Organization

$39 per month

30,000 searches/month included
API key access
Source retrieval and citation payloads
500 hosted chat answers/month
For B2B product integration
120 requests per minute per key

See pricing for current plans and rate limits for retry guidance.

Questions Developers Ask

Which MCP hosts does the Madeenan server work with?: Any MCP host that can start a local stdio server. The included config uses the mcpServers format from Claude Desktop and Cursor. VS Code uses a servers block, and Claude Code adds servers with claude mcp add.
Do I need an API key?: Not for the current source tools. Without a key, requests use the public service limits. Set MADEENAN_API_KEY in the host's server environment for plan limits. Never paste the key into a chat or tool argument.
Is there a hosted Quran MCP endpoint?: No. Madeenan does not run a public MCP endpoint. Run the server locally over stdio, or self-host Streamable HTTP behind an authenticated gateway.
Can the server answer religious questions or give fatwas?: No. It retrieves sources and prepares evidence for review. The assistant's reply is still model output, and interpretation belongs with qualified scholars.
Is the server on PyPI?: Not yet. The package is prepared for PyPI. Until it is published, setup needs a copy of the Madeenan repository, as the MCP setup docs describe.