# HadithDB [Health: Active]

**Category:** 🔮 Spirituality & Esoterica  
**Repository:** https://github.com/iadnanmukhtar/hadithdb  
**GitHub Stars:** 8  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hadithdb

## Description
Search and retrieve Quran ayahs, tafsir commentary, hadith, and detailed hadith records.

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "hadithdb": {
    "url": "https://hadithunlocked.com/mcp"
  }
}
```

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/hadithdb/readme_