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?
🔍 Intelligent Search (NEW!)
- 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
📖 Comprehensive Quran Access
- 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
📚 Tafsir (Commentary)
- 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
📜 Hadith Collections
- 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
🎵 Audio Recitations
- 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
⚡ Performance Features
- 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
🚀 Installation - Just Copy & Paste!
Step 1: Add to Your AI Agent
Claude Desktop - Add this to your config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"quran": {
"command": "npx",
"args": ["@quranmcp/server"]
}
}
}
Step 2: Restart Claude
Step 3: Done! 🎉
Ask: "Search the Quran for verses about patience"
Works with any MCP-compatible AI agent - just use the same JSON configuration!
🛠️ Available Tools (18 Total)
🔍 NEW! Search Tools (Revolutionary)
search_quran
Search the Quran by keywords or phrases - Find verses without knowing exact references!
{
"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!
{
"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!
{
"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!
{
"topic": "prayer",
"collections": ["bukhari"],
"max_results": 10
}
Available Topics: prayer, fasting, charity, hajj, faith, prophet, companions, knowledge, manners, family, marriage, death, jihad, repentance
📖 Quran Tools
get_quran_verse
Get a specific verse with Arabic text and translation.
{
"surah": 1,
"ayah": 1,
"translation": "en.asad"
}
get_full_surah
Get all verses of a complete Surah.
{
"surah": 1,
"include_translation": true,
"translation": "en.asad"
}
get_random_verse
Get a random verse for daily inspiration.
{
"include_translation": true,
"translation": "en.asad"
}
Tafsir Tools
get_tafsir
Get commentary/explanation for a verse.
{
"surah": 2,
"ayah": 255,
"tafsir": "en-tafisr-ibn-kathir"
}
list_tafsir_sources
List all available Tafsir sources.
Hadith Tools
get_hadith
Get a specific Hadith from a collection.
{
"collection": "bukhari",
"hadith_number": 1
}
get_random_hadith
Get a random Hadith.
{
"collection": "bukhari"
}
list_hadith_collections
List all available Hadith collections.
Recitation Tools
get_recitation_url
Get audio URL for a verse recitation.
{
"surah": 1,
"ayah": 1,
"reciter": "Maher_AlMuaiqly_64kbps"
}
list_reciters
List all available reciters.
Information Tools
get_surah_info
Get information about a Surah.
{
"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:
🔍 Search Queries (NEW!)
- "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"
📖 Traditional Queries
- "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?"
🎯 AI Understanding
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
Build
npm run build
Watch Mode
npm run dev
Testing with MCP Inspector
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
Before This Server:
- ❌ 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
With This Server:
- ✅ 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
Real-World Impact:
- 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:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📦 Package Information
- NPM Package: @quranmcp/server
- Version: 2.0.0
- License: MIT
- Repository: GitHub
- Size: 34.3 kB (compressed)
- Node.js: >= 18.0.0
📄 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
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- NPM: @quranmcp/server
📚 More Examples
See EXAMPLES.md for detailed usage examples.
Made with ❤️ for the Muslim community and AI enthusiasts
Status: 🟢 Live on NPM | ✅ Ready to Use | 🚀 Revolutionary Search Enabled