islamqa-org-mcp

Give Claude, Codex, and any other MCP client access to ~98,000 sourced fatwas.

An MCP server for IslamQA.org, which aggregates answers from 47 independent darul ifta institutions across the four Sunni madhahib.

Website · Install · ChatGPT · Tools · How it works · Etiquette

---

Why

Ask a language model a fiqh question and it will answer from a blur of training data, with no source, no madhhab, and no way to check it. That is the wrong shape for this kind of question.

This server changes the default. Your assistant searches a real archive of scholarly answers, and quotes one with the mufti, the madhhab, the institution, and a URL you can open. When the schools differ, you see that they differ instead of getting one position presented as the Islamic ruling.

You:  Can I wipe over ordinary cotton socks in wudu?

Claude: [searches IslamQA.org]

        The Hanafi position (Askimam.org, Mufti Ebrahim Desai) is that masah
        is only valid on socks with the characteristics of leather khuffayn —
        thick enough that water does not seep through, able to stand upright
        unaided, and durable over three to four miles of walking. Ordinary
        cotton socks do not qualify.
        https://islamqa.org/hanafi/askimam/127638/...

        Bin Bayyah (Maliki) notes the Hanbali school permits wiping over cloth
        socks, while the Maliki position restricts it to leather.
        https://islamqa.org/maliki/binbayyah/29891/...

Install

No clone, no manual setup. Pick whichever runner you already have.

With uv (recommended — it's what actually runs the server):

uvx --from git+https://github.com/RealYusufIsmail/islamqa-org-mcp islamqa-mcp

With npx, if Node is what you reach for:

npx -y islamqa-mcp

The npm package is a thin wrapper — it hands off to uv, which fetches and runs the Python server in an isolated cached environment. You still need uv installed; the wrapper tells you how if it's missing.

Installing uv

curl -LsSf https://astral.sh/uv/install.sh | sh    # macOS / Linux
brew install uv                                    # Homebrew
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows

Claude Code

claude mcp add islamqa -- uvx --from git+https://github.com/RealYusufIsmail/islamqa-org-mcp islamqa-mcp

Claude Desktop

Add to claude_desktop_config.json — on macOS, ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "islamqa": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/RealYusufIsmail/islamqa-org-mcp",
        "islamqa-mcp"
      ]
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.islamqa]
command = "uvx"
args = ["--from", "git+https://github.com/RealYusufIsmail/islamqa-org-mcp", "islamqa-mcp"]

Restart the client. The first search builds a local index (about a minute, ~22 requests); everything after that is instant.

From a local clone instead

git clone https://github.com/RealYusufIsmail/islamqa-org-mcp.git
cd islamqa-org-mcp && uv sync

Then point the client at it with uv --directory /absolute/path/to/islamqa-org-mcp run islamqa-mcp.

ChatGPT

ChatGPT is different from the clients above: it can't launch a local process, so it needs the server hosted at a public HTTPS URL. Two things follow.

1. Run it over HTTP instead of stdio.

islamqa-mcp --transport streamable-http --host 0.0.0.0 --port 8000

The endpoint ChatGPT wants is then https://your-host/mcp.

2. It exposes search and fetch in this mode. ChatGPT rejects any connector that doesn't have tools by exactly those names unless you've turned on Developer Mode, and Deep Research only ever calls those two. So when running over HTTP the server adds them as adapters over search_fatwas / get_fatwa, in OpenAI's required shape — search returns {id, title, url} per result, fetch returns {id, title, text, url, metadata}. Every result carries a real islamqa.org URL, so ChatGPT renders proper citations.

They are not registered for stdio, deliberately: Claude and Codex get the richer search_fatwas, and adding a weaker alias would just invite them to use the worse one.

Trying it without deploying

Run it locally and point a tunnel at it — this is what the Tunnel toggle in ChatGPT's connector dialog is for:

islamqa-mcp --transport streamable-http --port 8000
cloudflared tunnel --url http://localhost:8000     # or: ngrok http 8000

Then in ChatGPT: Settings → Apps → Advanced → Developer mode, add a connector pointing at https://<your-tunnel>/mcp, authentication None.

Hosting it properly

A Dockerfile is included and works on Render, Railway, Fly.io or Cloud Run:

docker build -t islamqa-mcp .
docker run -p 8000:8000 islamqa-mcp

It builds the URL index at image build time, which matters: the index costs ~22 requests to islamqa.org, and baking it into the image means that happens once per release rather than on every cold start of every replica. Without that, an autoscaling free tier would re-crawl the sitemap all day. It also makes the first user search instant.

Before you expose it publicly: a connector with no authentication is open to anyone who finds the URL, and every request they make is a request against islamqa.org under your server's name. Put it behind OAuth or an auth proxy if it isn't just for you, and keep the rate limit where it is.

The skill

An MCP server gives the model tools. It doesn't tell it how to use them well — and for fiqh, how matters more than what.

skills/islamqa-fatwa is a Claude skill that ships alongside the server. It makes the assistant:

• Ask which madhhab you follow before answering — or present all four positions side by side if you don't follow one
• Never issue a ruling it didn't retrieve. No invented hadith, no half-remembered "the Hanafi view is…", no fabricated Arabic citations. If the archive has nothing, it says so instead of filling the gap
• Use the tradition's actual categories rather than flattening everything to halal/haram — including the Hanafi seven-fold scheme, so makrūh taḥrīmī isn't quietly downgraded to "disliked" or upgraded to "haram"
• Say when coverage is thin. The archive is heavily Hanafi; if there's no Maliki answer, it reports that rather than inferring one
• Refer on for divorce, inheritance, custody and other matters that need a person rather than a search index

Install it globally:

git clone https://github.com/RealYusufIsmail/islamqa-org-mcp.git /tmp/islamqa-mcp
cp -r /tmp/islamqa-mcp/skills/islamqa-fatwa ~/.claude/skills/

It activates on its own when a question turns out to be a ruling question.

Tools

Tool	What it does
search_fatwas	Full-text search across the archive. Filter by madhhab or source.
get_fatwa	One answer in full: question, answer, Arabic citations, issuing institution.
list_sources	All 47 darul ifta sites with per-site answer counts.
browse_fatwas	Most recent answers, optionally filtered.
index_status	Index size, cache size, last rebuild.
rebuild_index	Refresh the index from the sitemap. Rarely needed.

Over HTTP, search and fetch are added for ChatGPT compatibility — see ChatGPT.

Every answer is returned with its attribution and a note reminding the model to cite the URL and to treat the ruling as one mufti's position, not a universal one.

Command line

The same operations without an MCP client:

uv run islamqa search "wiping over socks" --madhhab hanafi
uv run islamqa get https://islamqa.org/hanafi/askimam/127638/can-i-wipe-make-masah-over-the-new-socks/
uv run islamqa sources
uv run islamqa status

How it works

IslamQA.org runs WordPress with the REST API disabled, so there is no JSON endpoint to call. What it does publish is a complete sitemap and server-rendered pages — the same public pages any reader or search engine crawler sees.

The server works in two layers:

The index. One pass over the sitemap (~22 requests) records every answer URL along with its ID, madhhab, issuing source and a title derived from the slug. That is ~98,000 answers for a few megabytes and about a minute, and it means search is local and instant from then on.

The cache. Reading an answer fetches and parses that one page, then stores it. Search runs on an SQLite FTS5 index over both layers, so an answer is findable by title immediately and by its full text once anyone has read it — the archive gets more searchable the more you use it.

sitemap ──► index (~98k URLs + titles) ──┐
                                         ├──► FTS5 (BM25) ──► search_fatwas
answer page ──► parse ──► cache (full) ──┘                    get_fatwa

Because answers were imported from 47 different sites over many years, pages come in three template shapes, and all three are handled: the modern .ai-question / .ai-answer-content wrappers; bare paragraphs with explicit Question: / Answer: labels; and bare paragraphs with no labels at all. Stray Q: prefixes and trailing "Original Source Link" text are stripped, and Arabic endnotes citing classical texts are split into a separate citations field, so an answer reads cleanly without losing the evidence behind it.

Does islamqa.org have an API?

No public JSON API. The site runs WordPress, but the REST API is switched off site-wide. Probed August 2026:

Endpoint	Result
/wp-json/	401 — {"code":"rest_disabled"}
/wp-json/wp/v2/posts	401 — rest_disabled
/wp-json/wp/v2/search	401 — rest_disabled
/wp-json/elasticpress/v1/search	401 — rest_disabled
/graphql, /api/	404

The on-site search box is rendered client-side by ElasticPress, so its results aren't in the HTML either — which is why this server builds its own index rather than proxying site search.

What is machine-readable and open:

Endpoint	Format	Notes
/sitemap_index.xml	XML	22 child sitemaps
/sitemap-posts.xml?page=N	XML	5,000 answer URLs per page, with lastmod
/feed/	RSS 2.0	Latest answers site-wide
/category/{madhhab}/{source}/feed/	RSS 2.0	Latest per institution
Answer pages	HTML + JSON-LD	NewsArticle schema carries publish/modify dates
/robots.txt	—	Served empty: nothing disallowed

This server uses the sitemap and the answer pages. The RSS feeds are a lightweight option if you only want new answers and don't need search — they need no index and no scraping:

curl -s https://islamqa.org/hanafi/askimam/feed/

Answer URLs are structured, so you can address any answer directly:

https://islamqa.org/{madhhab}/{source}/{post_id}/{slug}/
                     hanafi   askimam  127638   can-i-wipe-make-masah-over-the-new-socks

If islamqa.org ever enables its REST API, this server should switch to it — open an issue if you notice it come back.

Configuration

All optional, set as environment variables:

Variable	Default	Purpose
ISLAMQA_DATA_DIR	~/.cache/islamqa-mcp	Where the index and cache live
ISLAMQA_REQUEST_DELAY	1.0	Seconds between requests
ISLAMQA_CACHE_TTL_DAYS	90	How long a cached answer stays fresh
ISLAMQA_INDEX_TTL_DAYS	30	When to rebuild the index
ISLAMQA_USER_AGENT	identifies this tool	Sent with every request

Etiquette (adab)

This reads a free service run on donations, so it is built to be a good guest:

• One request per second, serialised globally — concurrent tool calls cannot fan out into a burst.
• Caches aggressively. Fatwas are effectively immutable once published, so a page is fetched once and reused for 90 days.
• Fetches only what is asked for. The bulk pass reads the sitemap, not 100,000 answer pages. There is no crawler here.
• Identifies itself with a real User-Agent pointing back to this repo.
• Locked to one host. Every URL is checked against an allowlist before a socket opens, so no argument from a model can turn this into an open proxy.
• Attributes everything. The issuing institution, the mufti where named, and a link to the darul ifta's own copy travel with every answer.

If you maintain islamqa.org and want anything changed here — the rate limit, the User-Agent, or the tool's existence — please open an issue and it will be addressed.

On using this. These are answers from qualified muftis, but a fatwa is given to a particular person in a particular context. A search result is not a ruling on your situation, and a language model relaying one is not a scholar. For anything consequential, ask a qualified person directly.

Development

uv sync --extra dev
uv run pytest          # 81 tests, no network — runs against saved fixtures
uv run ruff check .
uv run mypy src/islamqa_mcp

The parser tests run against trimmed copies of real pages. If islamqa.org changes its template they fail loudly, which is deliberate: a silent parse regression would quietly feed empty answers to the model.

Licence

MIT — see LICENSE.

The licence covers this software only. The fatwas belong to the scholars and institutions that issued them. This tool reads public pages and links back; it does not redistribute the archive.