HadithDB MCP server

HadithDB

HadithDB (Hadith Unlocked) is a website for reading, searching, and citing the Quran and ḥadīth. You can browse it online at .

Every record keeps the original Arabic text alongside an English translation where one is available, together with chapter listings and grading information. For ḥadīth, the chain of narrators (isnād) and the report itself (matn) are stored separately so each can be read and searched on its own.

MCP server

HadithDB exposes a read-only, stateless Streamable HTTP MCP transport at POST /mcp. After this version is deployed, the public endpoint will be https://hadithunlocked.com/mcp. It provides Quran and tafsir lookup/search, hadith search, full hadith-detail lookup, and Quran audio tools.

Substantive research is available through researchislamictopic and researchquranayah. The topic tool takes a question, short Arabic/English queries, optional known hadith_references to anchor the evidence, and depth (brief, standard, or deep). It gathers discovery candidates, exact Quran/tafsir and hadith records, commentary from distinct works, and reports linked by verified internal references. Source numbers alone are never treated as cross-collection identities.

For ayah explanations, call researchquranayah with surah and ayah. Standard depth requests Tabari, Ibn Kathir and Qurtubi; deep adds Baghawi, Saadi and Ibn Ashur. Missing sources are reported rather than silently replaced. tafsirs overrides this selection. Read the returned texts, then call again with short grounded concepts to research relevant Quran/tafsir, hadith and shuruh. This is an assistant workflow within one turn, not a user follow-up. The tool does not pretend to infer semantic concepts on the server.

Dossiers distinguish direct tafsir, exact reports, source-linked reports, and conceptual search candidates. They return per-call found, searchednomatch, not_searched, or unavailable states, omissions and explicit next steps. Dossiers include selected source fields and bounded excerpts: discovery text is capped at 500 characters per field, retrieved source text at 3500, with truncation flags and exact lookup identifiers. They are not exhaustive surveys or generated rulings. A 25-second total deadline and depth-dependent call/source limits bound work; inspect coverage and retrieve truncated or omitted sources when consequential. Research depth does not dictate answer length.

listhadithcommentaries, searchhadithcommentary and lookuphadithcommentary expose the existing shuruh catalog and index. Search supports an exact commentary source alias and/or associated hadith reference; lookup uses an entry id. Compact hadith details now include research_inventory with commentary identities, work counts, and verified related references.

After deploying schema changes, update the published plugin/connection metadata and verify the tools visible in a fresh client session against tools/list. Publishing the JSON schema URL alone does not refresh an installed plugin’s schema snapshot. In particular, lookuphadithdetail must expose response_profile to clients as it does on the server.

The public tool schema is available at GET /mcp-server/schema.json, linked from /mcp-server. It includes the server and protocol versions and the same tool definitions returned by MCP tools/list, including input/output schemas and annotations. It is generated from the running server’s definitions and requires no MCP initialization or authentication.

Shortened. The full README is on GitHub.