Metadata-Version: 2.4
Name: widequran-mcp
Version: 0.1.1
Summary: MCP server for WideQuran — query Quran ayahs, surahs, hadith, and tafsir from Claude, Cursor, and Windsurf
Project-URL: Homepage, https://widequran.com
Project-URL: Repository, https://github.com/dobestan/widequran-mcp
Author: WideHoly
License-Expression: MIT
License-File: LICENSE
Keywords: ayah,claude,cursor,hadith,islamic,mcp,quran,surah,tafsir
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Religion
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]<2.0,>=1.0
Description-Content-Type: text/markdown

# widequran-mcp

[![PyPI version](https://img.shields.io/pypi/v/widequran-mcp)](https://pypi.org/project/widequran-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/widequran-mcp)](https://pypi.org/project/widequran-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

MCP server for [WideQuran](https://widequran.com) — query Quran ayahs, surahs, hadith collections, tafsir commentary, and Quranic figures directly from Claude, Cursor, and Windsurf. Access 114 surahs, 31,240 ayahs, 7,604 hadith, and multiple tafsir traditions through your AI assistant.

> **Browse the Quran at [widequran.com](https://widequran.com)** — 114 surahs, 31,240 ayahs across multiple translations, 7,604 hadith from major collections, tafsir commentary, and encyclopedic data on Quranic people and topics.

## Table of Contents

- [Install](#install)
- [Configure](#configure)
  - [Claude Desktop](#claude-desktop)
  - [Cursor](#cursor)
  - [Windsurf](#windsurf)
- [Available Tools](#available-tools)
- [Example Conversations](#example-conversations)
- [Quran Data Overview](#quran-data-overview)
- [Environment Variables](#environment-variables)
- [Also Available](#also-available)
- [WideHoly Scripture Platform](#wideholy-scripture-platform)
- [License](#license)

## Install

```bash
pip install widequran-mcp
```

Or with `uvx` (no install needed):

```bash
uvx widequran-mcp
```

## Configure

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

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

Or if installed with pip:

```json
{
  "mcpServers": {
    "widequran": {
      "command": "widequran-mcp"
    }
  }
}
```

### Cursor

Edit `~/.cursor/mcp.json`:

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

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

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

## Available Tools

| Tool | Description |
|------|-------------|
| `get_ayah` | Get a Quran ayah by surah and ayah number, with Arabic text and translation |
| `search_quran` | Search Quran text across all ayahs |
| `get_surah` | Get surah information — name, revelation type, ayah count |
| `get_hadith` | Get a hadith by collection and number, with grade and narrator |
| `get_tafsir` | Get tafsir (exegetical commentary) for a specific ayah |
| `get_person` | Get information about a Quranic person or prophet |

## Example Conversations

Once configured, ask your AI assistant:

- *"Show me Surah Al-Fatihah, ayah 1 with the Sahih translation"*
- *"Search the Quran for ayahs about mercy"*
- *"Tell me about Surah Yasin — how many ayahs does it have?"*
- *"Get hadith number 1 from Sahih Bukhari"*
- *"What does Ibn Kathir say about Surah 2, ayah 255 (Ayat al-Kursi)?"*
- *"Tell me about the prophet Ibrahim in the Quran"*
- *"Find Quran verses about patience and perseverance"*
- *"Get hadith number 25 from Sahih Muslim"*

The server calls the WideQuran API and returns structured data including Arabic text, translations, hadith grades, tafsir commentary, and biographical information.

## Quran Data Overview

| Category | Content |
|----------|---------|
| **Surahs** | 114 surahs (86 Meccan, 28 Medinan) |
| **Ayahs** | 31,240 ayahs across multiple translations (Sahih International, Pickthall, Yusuf Ali) |
| **Hadith** | 7,604 hadith from Bukhari, Muslim, Tirmidhi, Abu Dawud, and more |
| **Tafsir** | Commentary from Ibn Kathir, Al-Jalalayn, Al-Tabari, and others |
| **People** | Prophets and figures mentioned in the Quran (Ibrahim, Musa, Isa, Maryam, Yusuf) |
| **Structure** | 30 juz, 60 hizb, page and ruku markers |

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `WIDEQURAN_BASE_URL` | `https://widequran.com/api/v1/quran` | Override API base URL |

## Also Available

| Platform | Install | Link |
|----------|---------|------|
| **PyPI** | `pip install widequran` | [PyPI](https://pypi.org/project/widequran/) |

## WideHoly Scripture Platform

| Site | Domain | Focus |
|------|--------|-------|
| WideBible | [widebible.com](https://widebible.com) | Bible — 66 books, 31,102 verses, KJV and modern translations |
| **WideQuran** | [widequran.com](https://widequran.com) | **Quran — 114 surahs, 31,240 ayahs, hadith, tafsir** |
| WideTorah | [widetorah.com](https://widetorah.com) | Torah — Pentateuch, Talmud, Mishnah, Jewish commentary |
| WideGita | [widegita.com](https://widegita.com) | Bhagavad Gita — 18 chapters, 700 shlokas, Sanskrit and translations |
| WideSutra | [widesutra.com](https://widesutra.com) | Buddhist sutras — Pali Canon, Mahayana, Zen texts |
| WideHoly | [wideholy.com](https://wideholy.com) | Multi-religion scripture encyclopedia and cross-reference hub |

## Learn More About the Quran

- **Scripture**: [Surahs](https://widequran.com/) · [Translations](https://widequran.com/translations/)
- **Reference**: [People](https://widequran.com/people/) · [Topics](https://widequran.com/topics/) · [Glossary](https://widequran.com/glossary/)
- **Study**: [Tafsir](https://widequran.com/tafsir/) · [Hadith Collections](https://widequran.com/hadith/) · [Juz Divisions](https://widequran.com/juz/)
- **Tools**: [Search](https://widequran.com/) · [Developer Docs](https://widequran.com/developers/)
- **API**: [Developer Docs](https://widequran.com/developers/) · [OpenAPI Spec](https://widequran.com/api/schema/)

## License

MIT License — see [LICENSE](LICENSE) for details.
