A revolutionary Model Context Protocol server for Islamic resources - Search Quran & Hadith by keywords, access Tafsir, translations, and recitations. Works with any MCP-compatible AI agent.
npm install @quranmcp/server

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!
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"]
}
}
}
Install once, use forever:
`bash`
npm install -g @quranmcp/server
Claude Desktop Configuration:
`json`
{
"mcpServers": {
"quran": {
"command": "quran-mcp-server"
}
}
}
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"]
}
}
}
This server works with any MCP-compatible AI agent. Here's how to configure it:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json
Windows:
`json`
{
"mcpServers": {
"quran": {
"command": "npx",
"args": ["@quranmcp/server"]
}
}
}
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.
#### 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
#### 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"
}
#### 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.
#### 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.
#### 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.
#### 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.
Once configured, you can ask your AI assistant natural language questions:
``
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
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`)MIT License - feel free to use this in your projects!
- All the scholars and organizations who made these Islamic resources freely available
- The Model Context Protocol team at Anthropic
- The open-source community
For issues, questions, or suggestions, please open an issue on the repository.
---
Made with ā¤ļø for the Muslim community and AI enthusiasts