quran-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@quran-mcp-server show me verses from Surah Al-Fatihah"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Server for Quran.com API
MCP server to interact with Quran.com corpus via the official REST API v4.
Overview
This is a Model Context Protocol (MCP) server generated from the OpenAPI specification.
Related MCP server: Wasilah MCP
Endpoints
The following endpoints from the API have been made available as tools, that LLMs can use via compatible clients.
Chapters
GET /chapters - List Chapters
GET /chapters/{id} - Get Chapter
GET /chapters/{chapter_id}/info - Get Chapter Info
Verses
GET /verses/by_chapter/{chapter_number} - Get verses by Chapter / Surah number
GET /verses/by_page/{page_number} - Get all verses of a specific Madani Mushaf page
GET /verses/by_juz/{juz_number} - Get verses by Juz number
GET /verses/by_hizb/{hizb_number} - Get verses by Hizb number
GET /verses/by_rub/{rub_el_hizb_number} - Get verses by Rub el Hizb number
GET /verses/by_key/{verse_key} - Get verse by key
GET /verses/random - Get a random verse
Juzs
GET /juzs - Get list of all juzs
Search
GET /search - Search the Quran for specific terms
Translations
GET /resources/translations - Get list of available translations
GET /resources/translations/{translation_id}/info - Get information of a specific translation
Tafsirs
GET /resources/tafsirs - Get list of available tafsirs
GET /resources/tafsirs/{tafsir_id}/info - Get the information of a specific tafsir
GET /quran/tafsirs/{tafsir_id} - Get a single tafsir
Audio
GET /resources/chapter_reciters - List of Chapter Reciters
GET /resources/recitation_styles - Get the available recitation styles
Languages
GET /resources/languages - Get all languages
Setup
Requirements
Node.js 22+
Docker
Building the Docker Image
Before using the Docker-based production mode, you need to build the Docker image:
# Build the Docker image
docker build -t quran-mcp-server .Claude Desktop Integration
To use this MCP server with Claude Desktop, add the following configuration to your claude_desktop_config.json file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):
Docker-based Production Mode
{
"mcpServers": {
"quran-api": {
"command": "docker",
"args": ["run", "-i", "--rm", "--init", "-e", "API_KEY=your_api_key_if_needed", "-e", "VERBOSE_MODE=true", "quran-mcp-server"],
"disabled": false,
"autoApprove": []
}
}
}Production Mode (Node.js)
{
"mcpServers": {
"quran-api": {
"command": "node",
"args": ["/path/to/quran-mcp-server/dist/src/server.js"],
"env": {
"API_KEY": "your_api_key_if_needed",
"VERBOSE_MODE": "true" // Set to "true" to enable verbose logging
},
"disabled": false,
"autoApprove": []
}
}
}Development Mode
{
"mcpServers": {
"quran-api": {
"command": "npx",
"args": ["ts-node", "/path/to/quran-mcp-server/src/server.ts"],
"env": {
"API_KEY": "your_api_key_if_needed",
"VERBOSE_MODE": "true" // Set to "true" to enable verbose logging
},
"disabled": false,
"autoApprove": []
}
}
}Important Notes:
Replace
/path/to/quran-mcp-serverwith the actual path to this repository on your systemYou'll need to build the project first with
npm run buildordocker build -t quran-mcp-server .if using the production mode configurationReplace
your_api_key_if_neededwith an actual API key if required by the Quran.com APIIf you already have other MCP servers configured, add this configuration to the existing
mcpServersobjectAfter updating the configuration, restart Claude Desktop for the changes to take effect
Environment Variables
API_KEY: API key for authenticationPORT: Server port (default: 8000 or 3000 depending on language)VERBOSE_MODE: Set to 'true' to enable verbose logging of API requests and responses (default: false)
Verbose Mode
When VERBOSE_MODE is set to 'true', the server will log detailed information about API requests and responses to the console. This is useful for debugging and monitoring API interactions.
The verbose logging includes:
Requests: Logs the tool name and arguments for each incoming request
Responses: Logs the tool name and result data for each response
Errors: Logs detailed error information including error name, message, and stack trace when available
Each log entry is timestamped and prefixed with the log type (REQUEST, RESPONSE, or ERROR) for easy identification.
Testing
# Run tests
npm testLicense
This project is licensed under the MIT License.
Available Tools
20 toolschapter-recitersC
List of Chapter Reciters
Inputs: language.
GET-chapterD
Get Chapter
Inputs: language (required), id.
infoC
Get Chapter Info
Inputs: language (required), chapter_id.
juzsB
Get list of all juzs
Inputs: no named parameters.
languagesC
Get all languages
Inputs: language.
list-chaptersD
List Chapters
Inputs: language (required).
random_verseC
Get a random verse
Inputs: audio, fields, language, tafsirs, +4 more.
recitation-stylesB
Get the available recitation styles
Inputs: no named parameters.
searchC
Search the Quran for specific terms
Inputs: q (required), language, page, size.
tafsirC
Get a single tafsir
Inputs: tafsir_id (required), chapter_number, fields, hizb_number, +4 more.
tafsir-infoC
Get the information of a specific tafsir
Inputs: tafsir_id (required).
tafsirsC
Get list of available tafsirs
Inputs: language.
translation-infoC
Get information of a specific translation
Inputs: translation_id (required).
translationsC
Get list of available translations
Inputs: language.
verses-by_chapter_numberC
Get verses by Chapter / Surah number
Inputs: chapter_number (required), audio, fields, language, +7 more.
verses-by_hizb_numberC
Get verses by Hizb number
Inputs: hizb_number (required), audio, fields, language, +7 more.
verses-by_juz_numberC
Get verses by Juz number
Inputs: juz_number (required), audio, fields, language, +7 more.
verses-by_page_numberB
Get all verses of a specific Madani Mushaf page
Inputs: page_number (required), audio, fields, language, +7 more.
verses-by_rub_el_hizb_numberB
Get verses by Rub el Hizb number
Inputs: rub_el_hizb_number (required), audio, fields, language, +5 more.
verses-by_verse_keyC
Get verse by key
Inputs: verse_key (required), audio, fields, language, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools have distinct purposes, but there is some overlap between 'GET-chapter', 'info', and 'list-chapters' that could cause confusion, as they all relate to chapter information. The verses retrieval tools are well-differentiated by their indexing methods (e.g., chapter number, juz number).
Naming is inconsistent with mixed conventions: some use snake_case (e.g., 'random_verse'), some use kebab-case (e.g., 'chapter-reciters'), some use camelCase (e.g., 'verses-by_chapter_number'), and one uses uppercase prefix ('GET-chapter'). There is no uniform verb_noun pattern, making it harder to predict tool names.
With 20 tools, the count is borderline high for a Quran-focused server, but it covers various aspects like chapters, verses, recitations, tafsirs, and translations. It feels slightly heavy but still manageable given the domain's complexity.
The tool set provides comprehensive coverage for accessing Quranic content, including chapters, verses by multiple indices, recitations, translations, tafsirs, and search functionality. There are no obvious gaps for typical agent workflows in this domain.
Maintenance
Related MCP Connectors
Quran MCP server for translation, tafsir, mutashabihat, recitation playlists, and prayer times.
Quran MCP — Al-Quran Cloud API. Surahs (chapters), ayahs (verses), translations, and full-text…
Quran: Quran API Service with 90+ different languages and 400+ translations.
Unofficial Bible MCP — wraps the Bible API (free, no auth) https://bible-api.com
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server to search and retrieve passages from a corpus of 7,872 classical Islamic books via the Sahifah API, with full citations and mu'tabar filtering.MIT
- AlicenseNot gradedqualityCmaintenanceRemote MCP server exposing Wasilah's Islamic reference data, enabling prayer-time, Qibla, Hijri-date, and Quran-audio queries via natural language.MIT
- AlicenseNot gradedqualityCmaintenanceProvides AI clients with fast, hallucination-free access to the Quran through 13 MCP tools, covering search, navigation, morphology, tafsir, translations, and surah background over stdio and Streamable HTTP.MIT
- AlicenseAqualityCmaintenanceServes a scholar-approved Islamic corpus of Qur'an and hadith passages to any MCP client with server-side refusal enforcement. Enables natural-language questioning, retrieval, policy checking, and honest corpus coverage reporting while preventing fabricated answers.6MIT