LabscoMCP early access ↗
ovehbeMCP SERVER

Hadith MCP

Serve canonical hadith text with citations instead of letting a model quote from memory — semantic or keyword search, forgiving collection names, and cross-collection matches.

by ovehbe ↗Encyclopedic & Cultural ReferenceCommunity

LABSCO SUMMARY

The forgiving name matcher is what makes it usable in conversation.

People do not type canonical slugs. Accepting bukhari, sahih-bukhari, Sahih al-Bukhari and sahih_bukhari as the same collection is the difference between a citation tool that works mid-sentence and one that returns errors until you look up its identifiers. The other well-judged decision is the fallback: when the embedding provider refuses, search degrades to keyword rather than failing, so a quota problem does not become a blank answer. Building the database first is the real cost of entry.

What it is

An MCP server over a local SQLite database of hadith text in Arabic and English, plus the pipeline that builds it from the community hadith-json dataset. The design goal is citation safety: the assistant retrieves from a real corpus and cites it, rather than reconstructing a narration from training data.

What you get

  • The grounding rules returned once per session, so the assistant knows how it is expected to quote before it starts — fetch_grounding_rules
  • A hadith fetched by global id, or by collection plus number — including a string range like 1-5 — with cross references optionally attached; the collection argument accepts canonical slugs, common variants and human names alike — fetch_hadith
  • Search that defaults to semantic, with mode=keyword for SQL substring matching or mode=both; if the embedding provider returns a quota, billing or rate-limit error, it falls back to keyword search rather than failing — search_hadith
  • Algorithmic similarity matches for a hadith across collections, built from cosine similarity with narrator-aware scoring — fetch_cross_references
  • An interactive reader rendered in hosts that support MCP apps, always returning a plain-text fallback with the same citation URLs so other hosts still get a readable answer — show_hadith
  • A small REST surface over the same store for non-MCP use — /api/collections, /api/hadith/{id}, /api/search
  • Optional per-client rate limits and an LRU query cache to hold down cost

Requirements

The database has to be built before the server is useful: clone the hadith-json dataset locally and run the build script against its db/by_book directory. Semantic search additionally needs OPENAI_API_KEY and a database whose rows carry embeddings — the embedding pass is a long, checkpointed run and can be done on a separate machine, with checkpoints replayed afterwards. Keyword search works without either. Install with a virtualenv and pip install -e ".[dev]"; then hadith-mcp --transport stdio for desktop clients or --transport http. HADITH_MCP_DB_PATH overrides the database location and takes precedence over the config file. The pyproject name is hadith-mcp (0.1.0). Upstream attribution to the dataset authors and Sunnah.com is expected if you ship something on top of it.

Setup effort

Build from source — clone the repository, then follow the project's own run instructions

See installation options