Quran MCP Server

# Quran MCP Server 🕌 - Revolutionary Islamic AI Assistant [](https://www.npmjs.com/package/@quranmcp/server) [](https://opensource.org/licenses/MIT) 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` ```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! ```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 ### 📖 Quran Tools #### `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" } ``` ### Tafsir Tools #### `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. ### Hadith Tools #### `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. ### Recitation Tools #### `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. ### Information Tools #### `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: ### 🔍 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 ```bash npm run build ``` ### Watch Mode ```bash npm run dev ``` ### Testing with MCP Inspector ```bash npm run inspector ``` ## 📊 Data Sources This server aggregates data from multiple trusted Islamic resources: - **Tafsir**: [spa5k/tafsir_api](https://github.com/spa5k/tafsir_api) - **Hadith**: [fawazahmed0/hadith-api](https://github.com/fawazahmed0/hadith-api) - **Quran Arabic**: [fawazahmed0/quran-api](https://github.com/fawazahmed0/quran-api) - **Quran Translations**: [AlQuran Cloud API](https://alquran.cloud/api) - **Recitations**: [EveryAyah.com](https://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:** 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 ## 📦 Package Information - **NPM Package:** [@quranmcp/server](https://www.npmjs.com/package/@quranmcp/server) - **Version:** 2.0.0 - **License:** MIT - **Repository:** [GitHub](https://github.com/Prince77-7/quranMCP) - **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](https://github.com/Prince77-7/quranMCP/issues) - **Discussions:** [GitHub Discussions](https://github.com/Prince77-7/quranMCP/discussions) - **NPM:** [@quranmcp/server](https://www.npmjs.com/package/@quranmcp/server) ## 📚 More Examples See [EXAMPLES.md](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