Metadata-Version: 2.4
Name: quran-mcp
Version: 0.1.1
Summary: Quran, hadith and prayer times for Claude and other AI assistants (MCP server)
Author: ouchi-dev
License: MIT
Project-URL: Homepage, https://github.com/ouchi-dev/quran-mcp
Project-URL: Issues, https://github.com/ouchi-dev/quran-mcp/issues
Keywords: mcp,quran,hadith,prayer-times,islam,claude
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=2.3
Dynamic: license-file

# quran-mcp

<!-- mcp-name: io.github.ouchi-dev/quran-mcp -->

The Quran, the major hadith collections and prayer times, for Claude and any other
assistant that speaks the [Model Context Protocol](https://modelcontextprotocol.io).

Ask *"what does the Quran say about patience?"*, *"give me Ayat al-Kursi in Arabic and
French"*, *"find the hadith about intentions in Bukhari"* or *"when is Isha in Brussels
tonight?"*, and the assistant answers from the actual texts, **with the exact reference
for every quotation**, instead of paraphrasing from memory.

*Le Coran, les grands recueils de hadiths et les horaires de prière pour Claude et les
autres assistants IA. Chaque citation revient avec sa référence exacte (sourate:verset,
recueil et numéro), pour qu'une réponse puisse être vérifiée.*

## Tools

| Tool | What it does |
|---|---|
| `get_verses` | Arabic (Uthmani script) and translation of `2:255`, `2:255-257` or a whole surah, with juz and Mushaf page |
| `search_quran` | Verses containing every word of the query, in the translation or in Arabic (vowel marks ignored) |
| `list_surahs` | The 114 surahs: name, meaning, Meccan or Medinan, verse count |
| `list_translations` | About 440 translations in 90 languages (French: Hamidullah, Rashid Maash, ...) |
| `get_hadith`, `search_hadith` | Bukhari, Muslim, Abu Dawud, Tirmidhi, Nasa'i, Ibn Majah, Malik, Nawawi's 40, Qudsi; with grades when the collection has them |
| `prayer_times` | Computed locally from the sun's position: MWL, ISNA, Egypt, Umm al-Qura, Karachi, UOIF, Tehran; standard or Hanafi Asr; high latitude rule |

## Install

With [uv](https://docs.astral.sh/uv/) installed, nothing else is needed:

```bash
claude mcp add quran -- uvx quran-mcp
```

Or with pip: `pip install quran-mcp`, then `claude mcp add quran -- quran-mcp`.

Claude Desktop (`claude_desktop_config.json`):

```json
{ "mcpServers": { "quran": { "command": "uvx", "args": ["quran-mcp"] } } }
```

Texts are downloaded on first use (about 1.5 MB per Quran edition, a few MB per hadith
collection) into `~/.cache/quran-mcp` and read from disk afterwards. Set
`QURAN_MCP_CACHE` to put them elsewhere.

## Accuracy

- **Texts** come from the open [quran-api](https://github.com/fawazahmed0/quran-api) and
  [hadith-api](https://github.com/fawazahmed0/hadith-api) datasets. Nothing is
  generated or reworded by this server.
- **Prayer times** match [Aladhan](https://aladhan.com) to the minute for Fajr, sunrise,
  Dhuhr, Maghrib and Isha (tested in Brussels, Makkah, Casablanca and Sydney, summer and
  winter). Asr follows the exact shadow definition checked against the NOAA solar model,
  which can be one to three minutes earlier than Aladhan. Local mosques often add a few
  minutes of precaution: their timetable comes first.
- The server gives **sources, not rulings**. Its instructions tell the assistant to quote
  references and to send fiqh questions to a qualified scholar.

## Roadmap

- [x] Quran: verses, passages, surahs, Arabic search, 440 translations
- [x] Hadith: 10 collections, lookup and search
- [x] Prayer times, offline, 7 methods
- [ ] Search by meaning (French "prière" should find Hamidullah's "Salât")
- [ ] Tafsir Ibn Kathir and al-Jalalayn
- [ ] Word-by-word Arabic, roots and transliteration
- [ ] Hijri calendar and important dates
- [ ] Qibla direction
- [ ] Recitation audio links per verse

Comes from [Isuramu](https://github.com/0uchii), an offline Quran app for Android.

## License

MIT for the code. The texts keep the terms of their sources.
