hadathna-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hadathna-mcp ما هو حديث بدء الوحي؟"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hadathna-mcp
An MCP server over Sahih al-Bukhari: its hadiths, their chains of narrators, and the narrators' biographies. Any MCP client (Claude, Codex, Cursor, VS Code, your own agent) can ask it questions, and the model answers with hadith numbers it can cite.
It reads the public Hadathna API (https://api.hadathana.app). No key, no account.
Tools
Tool | What it does |
| Search by words in the text, narrator, book or topic |
| The whole entry for a hadith number: sanad, matn, tawabi, chains |
| Find a narrator's |
| Name, rank, hadith count, top teachers and students |
| What the classical tarajim books say, source by source |
| The topics hadiths are tagged with |
All tools are read-only. Inputs are Arabic; diacritics and hamza forms do not matter.
The evals in evals/ score 20 Arabic questions end to end — the answer, the tools called and
the bytes those tools returned — without an LLM judge; evals/README.md shows how to run them.
Related MCP server: hadith-mcp
Install
It needs uv. uvx downloads and runs the one version you pin.
Claude Code
claude mcp add hadathna -- uvx hadathna-mcp@0.1.0Claude Desktop, Cursor, VS Code (the mcpServers block of the client's config)
{
"mcpServers": {
"hadathna": { "command": "uvx", "args": ["hadathna-mcp@0.1.0"] }
}
}Codex (~/.codex/config.toml)
[mcp_servers.hadathna]
command = "uvx"
args = ["hadathna-mcp@0.1.0"]Then ask, for example: «ما هو حديث بدء الوحي؟» or «من هو أبو هريرة؟».
Settings
Variable | Default | Use |
|
| Point at another copy of the API, such as a local one |
Source
github.com/abdelrahmaan/hadathna-mcp.
License
MIT. See LICENSE.
Available Tools
6 toolsget_hadithARead-only
Get every entry that holds a hadith number: sanad, matn, tawabi and chains.
A number can sit in more than one entry (221, 4952 and 5472 do), and an entry can hold several consecutive hadiths; hadith_numbers lists them all.
Inputs: number (required). Returns: Every entry that holds one hadith number: two, for 221, 4952 and 5472.
get_narratorARead-only
Get a narrator's name, rank, hadith count, and top teachers and students.
Teachers and students are ranked by the hadiths they share with this narrator.
Inputs: narrator_id (required), limit. Returns: era, rank, kunya, location, +9 more
get_narrator_biographyARead-only
Get what the classical books of tarajim say about a narrator, source by source.
Long: call it only when the user asks about the narrator's life or reliability.
Inputs: narrator_id (required). Returns: url, sources, narrator_id
list_topicsARead-only
List the topics hadiths are tagged with, and how many entries carry each.
Use it to find the exact topic name before search_hadiths(topic=...), which matches the name exactly.
Inputs: no named parameters. Returns: items
search_hadithsARead-only
Search Sahih al-Bukhari's hadiths by words in the text, narrator, book or topic.
Filters combine (AND). Each result is an entry with its hadith numbers and its whole matn; call get_hadith for the sanad, the chains and the full text.
total is how many entries match. To count, call with limit=1 and read total. A total of 0 means nothing matched: try a shorter phrase, or check the topic with list_topics.
Inputs: book, limit, query, topic, +2 more. Returns: total, offset, results, next_offset
search_narratorsARead-only
Find narrators by name, to get the narrator_id the other tools take.
Inputs: name (required), limit, offset. Returns: total, offset, results, next_offset
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Search vs. fetch pairs are clearly separated (search_hadiths/get_hadith, search_narrators/get_narrator), and list_topics is unambiguous. The one soft boundary is get_narrator vs get_narrator_biography: get_narrator already reports rank/reliability, while the biography tool covers classical-source material on 'life or reliability', so an agent may hesitate between them, though the descriptions give a usable rule of thumb.
Every tool follows a clean verb_noun snake_case pattern: search_*, get_*, list_*. The singular get_hadith vs plural search_hadiths is a deliberate semantic distinction (fetch one number vs. search many), not an inconsistency.
Six tools is a tight, well-scoped set for a single-collection hadith corpus: two search tools, two fetch tools, a biography lookup, and a topic directory. It is on the lean side — nothing for browsing books/chapters directly — but each tool clearly earns its place.
Core lifecycles are covered: discover via search (hadith, narrator, topic), then retrieve full entries with sanad/matn/chains and narrator details. The notable gap is that topics get a list_topics discovery helper for exact-name matching, but 'book' is also a search filter with no equivalent listing tool, so agents must guess book names; a book/chapter listing would close the loop.
Maintenance
Related MCP Connectors
Search and retrieve Quran ayahs, tafsir commentary, hadith, and detailed hadith records.
Quran, hadith collections and tafsirs: browse books and chapters, read verses, full-text search
Quran MCP — Al-Quran Cloud API. Surahs (chapters), ayahs (verses), translations, and full-text…
Islamic prayer times & calendar MCP (Aladhan API). Keyless.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables fetching and searching canonical hadith texts (Arabic and English) with cross-references and citation-safe URLs for assistants, built on FastMCP.3GPL 3.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server for retrieving hadith text and metadata from auditable sources, providing exact references, Arabic text, English translations, and source-attributed grading.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server to search and retrieve passages from a corpus of 7,872 classical Islamic books via the Sahifah API, with full citations and mu'tabar filtering.MIT
- AlicenseNot gradedqualityCmaintenanceProvides AI clients with fast, hallucination-free access to the Quran through 13 MCP tools, covering search, navigation, morphology, tafsir, translations, and surah background over stdio and Streamable HTTP.MIT