Quran MCP Server 🕌 - Revolutionary Islamic AI Assistant


A revolutionary Model Context Protocol (MCP) server that gives AI assistants powerful access to Islamic resources. The first MCP server with intelligent keyword search for Quran and Hadith - no more needing exact verse numbers!

✨ What Makes This Revolutionary?

$3

- Search Quran by Keywords: Find verses about "patience", "prayer", "mercy" without knowing verse numbers
- Search Hadith by Topics: Discover hadiths about "charity", "fasting", "manners" instantly
- Topic-Based Discovery: AI understands common Islamic topics and finds relevant content
- Natural Language Queries: Ask "find verses about patience" and get instant results

$3

- Arabic Text: Original Quranic text in Arabic
- Multiple Translations: English translations from renowned scholars (Asad, Sahih International, Pickthall, Yusuf Ali, Hilali & Khan)
- Full Surah Retrieval: Get complete chapters with or without translations
- Random Verse: Daily inspiration feature
- Verse-by-Verse Access: Traditional reference-based lookup

$3

- Multiple Sources: Access to various Tafsir collections
- Tafsir Ibn Kathir (English & Arabic)
- Maarif-ul-Quran
- Tafsir al-Tabari (Arabic)
- Tafsir al-Qurtubi (Arabic)
- Verse-by-verse Explanations: Detailed scholarly commentary

$3

- Six Major Collections:
- Sahih Bukhari (7,563 hadiths)
- Sahih Muslim (7,563 hadiths)
- Sunan Abu Dawud (5,274 hadiths)
- Jami' at-Tirmidhi (3,956 hadiths)
- Sunan an-Nasa'i (5,758 hadiths)
- Sunan Ibn Majah (4,341 hadiths)
- Random Hadith: Daily hadith feature

$3

- Multiple Reciters: Choose from renowned Quran reciters
- Maher Al-Muaiqly
- Abdul Basit
- Abdurrahman As-Sudais
- Mishary Rashid Alafasy
- Mahmoud Khalil Al-Hussary
- High-Quality Audio: MP3 format in various bitrates
- Playlist Generation: M3U playlists for full Surahs

$3

- Intelligent Caching: LRU cache with TTL to minimize API calls
- Error Handling: Comprehensive error handling with meaningful messages
- Type Safety: Full TypeScript implementation with strict mode
- Validation: Input validation for all parameters

🚀 Quick Start - 3 Ways to Use

$3

The fastest way - works immediately with any MCP-compatible AI:

``bash
npx @quranmcp/server
`

Claude Desktop Configuration:
`json
{
"mcpServers": {
"quran": {
"command": "npx",
"args": ["@quranmcp/server"]
}
}
}
`

$3

Install once, use forever:

`bash
npm install -g @quranmcp/server
`

Claude Desktop Configuration:
`json
{
"mcpServers": {
"quran": {
"command": "quran-mcp-server"
}
}
}
`

$3

For contributors and developers:

`bash
git clone https://github.com/Prince77-7/quranMCP.git
cd quranMCP
npm install
npm run build
`

Claude Desktop Configuration:
`json
{
"mcpServers": {
"quran": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/quranMCP/dist/index.js"]
}
}
}
`

🌐 Universal MCP Configuration

This server works with any MCP-compatible AI agent. Here's how to configure it:

$3

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

`json
{
"mcpServers": {
"quran": {
"command": "npx",
"args": ["@quranmcp/server"]
}
}
}
`

$3

The server uses standard MCP protocol and works with:
- Claude Desktop (Anthropic)
- ChatGPT with MCP (when available)
- Any MCP-compatible AI agent

Simply use the same configuration format with npx @quranmcp/server as the command.

🛠️ Available Tools (18 Total)

$3

#### search_quran
Search the Quran by keywords or phrases - Find verses without knowing exact references!
`json
{
"query": "patience",
"translation": "en.sahih",
"max_results": 20
}
`

Example Queries:
- "patience" - Find all verses about patience
- "those who believe" - Find verses with this phrase
- "prayer" - Discover verses about prayer
- "mercy forgiveness" - Multiple keywords

#### search_hadith
Search Hadith collections by keywords - Discover hadiths about any topic!
`json
{
"query": "charity",
"collections": ["bukhari", "muslim"],
"max_results": 20
}
`

Example Queries:
- "prayer times" - Find hadiths about prayer
- "fasting ramadan" - Hadiths about fasting
- "parents" - Hadiths about treating parents

#### search_quran_by_topic
Search by predefined Islamic topics - AI-optimized topic search!
`json
{
"topic": "patience",
"translation": "en.sahih",
"max_results": 10
}
`

Available Topics: prayer, patience, charity, faith, paradise, hell, prophet, allah, mercy, justice, knowledge, family, death, creation, guidance

#### search_hadith_by_topic
Search Hadith by Islamic topics - Topic-based hadith discovery!
`json
{
"topic": "prayer",
"collections": ["bukhari"],
"max_results": 10
}
`

Available Topics: prayer, fasting, charity, hajj, faith, prophet, companions, knowledge, manners, family, marriage, death, jihad, repentance

$3

#### get_quran_verse
Get a specific verse with Arabic text and translation.
`json
{
"surah": 1,
"ayah": 1,
"translation": "en.asad"
}
`

#### get_full_surah
Get all verses of a complete Surah.
`json
{
"surah": 1,
"include_translation": true,
"translation": "en.asad"
}
`

#### get_random_verse
Get a random verse for daily inspiration.
`json
{
"include_translation": true,
"translation": "en.asad"
}
`

$3

#### get_tafsir
Get commentary/explanation for a verse.
`json
{
"surah": 2,
"ayah": 255,
"tafsir": "en-tafisr-ibn-kathir"
}
`

#### list_tafsir_sources
List all available Tafsir sources.

$3

#### get_hadith
Get a specific Hadith from a collection.
`json
{
"collection": "bukhari",
"hadith_number": 1
}
`

#### get_random_hadith
Get a random Hadith.
`json
{
"collection": "bukhari"
}
`

#### list_hadith_collections
List all available Hadith collections.

$3

#### get_recitation_url
Get audio URL for a verse recitation.
`json
{
"surah": 1,
"ayah": 1,
"reciter": "Maher_AlMuaiqly_64kbps"
}
`

#### list_reciters
List all available reciters.

$3

#### get_surah_info
Get information about a Surah.
`json
{
"surah": 1
}
`

#### list_surahs
List all 114 Surahs with their information.

#### list_translations
List all available translations.

#### get_cache_stats
Get cache statistics for monitoring.

💬 Example Queries for AI Assistants

Once configured, you can ask your AI assistant natural language questions:

$3

- "Find verses about patience in the Quran"
- "Search for hadiths about charity"
- "Show me Quranic verses about prayer"
- "Find hadiths about treating parents"
- "What does the Quran say about mercy?"
- "Search for verses containing 'those who believe'"
- "Find hadiths about fasting in Ramadan"

$3

- "Show me Ayat al-Kursi (verse 2:255) with translation and tafsir"
- "Get me a random verse from the Quran for today"
- "What does Surah Al-Fatiha say?"
- "Show me hadith number 1 from Sahih Bukhari"
- "Give me a random hadith"
- "Get the audio recitation URL for Surah Yasin"
- "List all available Quran translations"
- "What is the information about Surah Al-Baqarah?"

$3

The AI assistant now understands it can:
- Search by keywords instead of requiring exact verse numbers
- Find content by topic without knowing references
- Discover related verses and hadiths through natural language
- Combine search with traditional lookup for comprehensive study

🏗️ Architecture

`
quranMCP/
├── src/
│ ├── index.ts # Main MCP server
│ ├── types/ # TypeScript type definitions
│ │ └── index.ts
│ ├── constants/ # Constants and validation
│ │ └── index.ts
│ ├── services/ # Core services
│ │ ├── cache.ts # Caching layer
│ │ └── fetcher.ts # HTTP client
│ └── tools/ # Tool implementations
│ ├── quran.ts # Quran text & translations
│ ├── tafsir.ts # Tafsir commentary
│ ├── hadith.ts # Hadith collections
│ └── recitation.ts # Audio recitations
├── dist/ # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
`

🔧 Development

$3


`bash
npm run build
`

$3

`bash
npm run dev
`

$3

`bash
npm run inspector
`

📊 Data Sources

This server aggregates data from multiple trusted Islamic resources:

- Tafsir: spa5k/tafsir_api
- Hadith: fawazahmed0/hadith-api
- Quran Arabic: fawazahmed0/quran-api
- Quran Translations: AlQuran Cloud API
- Recitations: EveryAyah.com

🎯 Why This MCP Server is Revolutionary

$3

- ❌ Had to know exact Surah and Ayah numbers
- ❌ Couldn't search by keywords or topics
- ❌ Required manual lookup in external resources
- ❌ Limited to reference-based queries

$3

- ✅ Natural language search - "find verses about patience"
- ✅ Keyword-based discovery - Search entire Quran and Hadith collections
- ✅ Topic-aware AI - AI understands Islamic topics and finds relevant content
- ✅ Universal compatibility - Works with any MCP-compatible AI agent
- ✅ Zero-install option - Use with NPX instantly
- ✅ Intelligent caching - Fast responses with smart caching
- ✅ 18 powerful tools - Comprehensive Islamic resource access

$3

- Students: Discover verses and hadiths for research without memorizing references
- Educators: Quickly find relevant Islamic texts for teaching
- Researchers: Search across multiple sources simultaneously
- Daily Users: Get instant answers to Islamic questions
- Developers: Build Islamic AI applications with ease

🤝 Contributing

Contributions are welcome! This is an open-source project for the Muslim community.

Priority Areas:
- Additional Tafsir sources (more languages)
- More Hadith collections
- Additional translations (Urdu, Arabic, French, etc.)
- Enhanced search algorithms
- Thematic indexing improvements
- Juz/Hizb navigation
- Performance optimizations

How to Contribute:
1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

📄 License

MIT License - feel free to use this in your projects!

🙏 Acknowledgments

- All the scholars and organizations who made these Islamic resources freely available
- The Model Context Protocol team at Anthropic
- The open-source community

📞 Support

For issues, questions, or suggestions, please open an issue on the repository.

---

Made with ❤️ for the Muslim community and AI enthusiasts