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:

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
• 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