Skip to main content
Glama

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_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.

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.0

Claude 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

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.

License

MIT. See LICENSE.

Available Tools

6 tools
get_hadithA
Read-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_narratorA
Read-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_biographyA
Read-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_topicsA
Read-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_hadithsA
Read-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_narratorsA
Read-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

    A4/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables fetching and searching canonical hadith texts (Arabic and English) with cross-references and citation-safe URLs for assistants, built on FastMCP.
      3
      GPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for retrieving hadith text and metadata from auditable sources, providing exact references, Arabic text, English translations, and source-attributed grading.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides 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