Madeenan: Quran and Hadith API clients and MCP server

Open-source clients for the Madeenan 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	see packages/sdk/README.md
React components @madeenan/react	packages/react	see packages/react/README.md
React Native components @madeenan/react-native	packages/react-native	see packages/react-native/README.md
Python SDK madeenan-sdk	packages/python	see packages/python/README.md
MCP server madeenan-mcp	apps/mcp	see apps/mcp/README.md

Quick example (TypeScript)

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
• Hadith API
• Quran MCP server
• Documentation
• Pricing
• Find the source of a quote

The API contract the SDKs are tested against is in contracts/public-openapi.json.

License

MIT. See LICENSE.