hadathna-mcp
# 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.
<!-- mcp-name: io.github.abdelrahmaan/hadathna-mcp -->
## Tools
| Tool | What it does |
|---|---|
| `search_hadiths` | Search by words in the text, narrator, book or topic |
| `get_hadith` | The whole entry for a hadith number: sanad, matn, tawabi, chains |
| `search_narrators` | Find a narrator's `narrator_id` by name |
| `get_narrator` | Name, rank, hadith count, top teachers and students |
| `get_narrator_biography` | What the classical tarajim books say, source by source |
| `list_topics` | 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.
## Install
It needs [uv](https://docs.astral.sh/uv/). `uvx` downloads and runs the one version you pin.
**Claude Code**
```bash
claude mcp add hadathna -- uvx hadathna-mcp@0.1.0
```
**Claude Desktop, Cursor, VS Code** (the `mcpServers` block of the client's config)
```json
{
"mcpServers": {
"hadathna": { "command": "uvx", "args": ["hadathna-mcp@0.1.0"] }
}
}
```
**Codex** (`~/.codex/config.toml`)
```toml
[mcp_servers.hadathna]
command = "uvx"
args = ["hadathna-mcp@0.1.0"]
```
Then ask, for example: «ما هو حديث بدء الوحي؟» or «من هو أبو هريرة؟».
## Settings
| Variable | Default | Use |
|---|---|---|
| `HADATHNA_API_URL` | `https://api.hadathana.app` | Point at another copy of the API, such as a local one |
## Source
[github.com/abdelrahmaan/hadathna-mcp](https://github.com/abdelrahmaan/hadathna-mcp).
## License
MIT. See [LICENSE](LICENSE).
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.