HadithDB

What HadithDB MCP server does

The HadithDB MCP server gives MCP clients read-only access to Quran and hadith content from Hadith Unlocked. Records can include Arabic text, English translations, chapter information, grading, narrator chains, report text, tafsir, and hadith commentary. Arabic and English values remain separate, and unavailable language fields are returned as null rather than generated.

The server supports both focused retrieval and broader research workflows. Quran tools cover ayah search, tafsir lookup, page and passage navigation, Mushaf layout information, and editorial headings. Hadith tools search reports, retrieve complete details, inspect commentary, and expose verified related references. Quran audio tools return playback and timing data rather than playing audio themselves.

How it works

The HadithDB MCP server uses a read-only, stateless Streamable HTTP endpoint at POST /mcp. It accepts JSON-RPC requests for initialization, health checks, tool discovery, tool calls, skills, and resource reads. Clients should not expect an Mcp-Session-Id header because the service does not create sessions.

Research tools assemble evidence from multiple source types. research_islamic_topic accepts a question, short Arabic or English queries, optional hadith references, and a depth setting. research_quran_ayah starts with a surah and ayah, then can be called again with grounded concepts based on the returned texts. Results distinguish direct tafsir, exact reports, source-linked reports, and conceptual candidates. Coverage states identify material that was found, searched without a match, not searched, or unavailable.

Tools and capabilities

Available capabilities include:

• Search Quran translations and canonical ayahs with pagination.
• Find tafsir works and retrieve commentary with selectable response profiles.
• Search hadith and retrieve detailed records, attribution, grading, isnad, matn, and related references.
• List, search, and look up hadith commentaries by source, reference, or entry ID.
• Research Quran ayahs and Islamic topics using bounded, source-aware dossiers.
• Inspect Quran pages, sections, subsections, passages, headings, ranges, and word boundaries.
• List Quran reciters and obtain surah or passage audio URLs with ayah timing segments.

Long responses support compact, default, and full profiles where applicable. Research dossiers include identifiers, omissions, excerpts, and truncation indicators so clients can request consequential material separately.

Setup and configuration

Connect an MCP client to https://hadithunlocked.com/mcp using Streamable HTTP. The public schema is available at https://hadithunlocked.com/mcp-server/schema.json; it describes the running server, protocol versions, tools, and input/output schemas without requiring authentication or MCP initialization.

Deployments can set HADITHDB_MCP_HADITH_BASE_URL and HADITHDB_MCP_QURAN_BASE_URL to change backing services. MCP_ALLOWED_ORIGINS adds browser origins, while MCP_RATE_LIMIT_WINDOW_MS and MCP_RATE_LIMIT_PER_IP adjust rate limits. These settings are optional overrides, not prerequisites for the public endpoint.

Limitations and notes

Search requests enforce a ten-second deadline, scan no more than six underlying pages per call, and reject logical offsets above 500. Research has a 25-second total deadline and depth-dependent source and call limits. Dossiers are bounded rather than exhaustive surveys and are not generated rulings.

Audio calls return URLs and millisecond boundaries; the client must play, seek, and stop the media. Incomplete timing coverage produces an error, and media-fragment support depends on the player. Request limits include a 64 KiB body cap and per-IP rate limiting. When source text is truncated or omitted, inspect the returned flags and identifiers before relying on it.