madeenan
# Madeenan: Quran and Hadith API clients and MCP server
Open-source clients for the [Madeenan](https://madeenan.com) Quran and Hadith API. Search Quran, Hadith, Tafsir and dua sources, read exact references, check where a quote comes from, and get answers that cite their sources.
The search, ranking and source data run on the hosted Madeenan API. This repository contains the client libraries and the MCP server that call it.
| Package | Path | Install |
| --- | --- | --- |
| TypeScript SDK `@madeenan/sdk` | [`packages/sdk`](packages/sdk) | see [packages/sdk/README.md](packages/sdk/README.md) |
| React components `@madeenan/react` | [`packages/react`](packages/react) | see [packages/react/README.md](packages/react/README.md) |
| React Native components `@madeenan/react-native` | [`packages/react-native`](packages/react-native) | see [packages/react-native/README.md](packages/react-native/README.md) |
| Python SDK `madeenan-sdk` | [`packages/python`](packages/python) | see [packages/python/README.md](packages/python/README.md) |
| MCP server `madeenan-mcp` | [`apps/mcp`](apps/mcp) | see [apps/mcp/README.md](apps/mcp/README.md) |
## Quick example (TypeScript)
```ts
import { createMadeenanClient } from "@madeenan/sdk";
const madeenan = createMadeenanClient({ apiKey: process.env.MADEENAN_API_KEY });
const search = await madeenan.search({
q: "patience and prayer",
indexes: ["quran", "hadith"],
});
for (const result of search.results.quran ?? []) {
console.log(result.ref, result.excerpt ?? result.translation);
}
```
Keep the API key on your server. Do not put it in code that runs in a browser.
## MCP tools
The MCP server lets Claude, Cursor and other MCP clients look up sources instead of answering from memory:
- `search_islamic_sources`: search Quran, Hadith, Tafsir and dua records.
- `lookup_quran_reference`: read a verse, chapter or passage.
- `lookup_hadith_reference`: read a Hadith with its recorded grade.
- `lookup_dua`: read a dua or adhkar item.
- `find_quote_source`: find where a wording appears. A match does not prove authorship.
- `create_evidence_bundle` and `review_evidence_claim`: collect sources for a claim and prepare a checklist. They do not verify a claim or its meaning.
## Links
- [Quran API](https://madeenan.com/quran-api)
- [Hadith API](https://madeenan.com/hadith-api)
- [Quran MCP server](https://madeenan.com/quran-mcp-server)
- [Documentation](https://madeenan.com/docs)
- [Pricing](https://madeenan.com/pricing)
- [Find the source of a quote](https://madeenan.com/find-a-source)
The API contract the SDKs are tested against is in [`contracts/public-openapi.json`](contracts/public-openapi.json).
## License
MIT. See [LICENSE](LICENSE).
TDQS
Scored across 7 tools
The three lookup tools are cleanly separated by source type (dua, Quran, Hadith), and the evidence bundle/review pair serves clearly different roles (assembly vs. checklist review). The main overlap is between search_islamic_sources and find_quote_source, which both take text and return source matches; the descriptions hint at the difference (query search vs. quote wording match) but an agent could still pick the wrong one.
Every tool follows a snake_case verb_noun pattern (lookup_*, find_*, search_*, create_*, review_*), with nouns that map to the resource being touched. No mixing of conventions or vague single-word names.
Seven tools is well within the ideal range and each one earns its place: three source lookups, one cross-source search, one quote matcher, and two evidence-workflow helpers. Nothing looks like filler or a near-duplicate.
The surface covers the core lifecycle of source lookup (dua, Quran, Hadith, plus tafsir via search) and adds an evidence collection/review workflow, which is coherent for the stated purpose. Gaps remain: there is no tool to enumerate valid collection slugs or available sources, and tafsir has no direct reference lookup, so an agent must guess slugs or go through generic search.