Quran

You can run and query a powerful MCP server that gives your AI agents fast access to Quran, Hadith, Tafsir, and recitations through natural language searches and topic-based discovery. It enables keyword searches, verse lookups, and audio playback across multiple Islamic sources, all via a lightweight MCP interface that works with any compatible agent.

How to use

You connect an MCP-compatible AI agent to the server, then ask natural language questions to search across Quran, Hadith, Tafsir, and recitations. Use keywords or topics to find verses, hadiths, or explanations without needing exact chapter and verse numbers. You can also request specific verses, surahs, or audio recitations, and combine traditional lookups with broad search results for comprehensive study.

How to install

Prerequisites: you need Node.js installed on your system. Use a supported runtime (Node.js 18 or newer). You also need an environment where you can run npm commands.

1. Add the MCP server to your setup by running the following configuration snippet in your client or agent configuration. This enables the quran MCP server as a local stdio process.

{
  "mcpServers": {
    "quran": {
      "command": "npx",
      "args": ["@quranmcp/server"]
    }
  }
}

Basic setup steps

2. Ensure your agent reads the configuration and can spawn the MCP server described above. This typically involves placing the snippet in the agent’s config file and restarting the agent.

3. Restart your AI agent or IDE integration so it picks up the new MCP server configuration.

4. Start using natural language queries such as “Find verses about patience in the Quran” or “Show me hadiths about charity.” The agent will route requests to the MCP server and present results from Quran, hadiths, tafsir, and recitations.

Configuration notes

The server exposes a set of tools you can call via the MCP interface. Tools include search by Quran keywords, search by hadith topics, verse retrieval, random verses, tafsir lookups, and recitation URLs. If you need to customize how the server is started, you can modify the client-side configuration to point to the local npm-based command shown above.

Available tools

search_quran

Search the Quran by keywords or phrases to find verses without needing exact references.

search_hadith

Search Hadith collections by keywords to discover hadiths on any topic.

search_quran_by_topic

Search Quran content by predefined topics with optional translations.

search_hadith_by_topic

Search Hadith by predefined Islamic topics across collections.

get_quran_verse

Retrieve a specific verse with Arabic text and translation.

get_full_surah

Get all verses of a complete Surah, with optional translation.

get_random_verse

Fetch a random Quran verse for daily inspiration.

get_tafsir

Get verse-by-verse Tafsir explanations from selected sources.

list_tafsir_sources

List available Tafsir sources for reference.

get_hadith

Retrieve a specific Hadith from a collection by its number.

get_random_hadith

Get a random Hadith from a specified collection.

list_hadith_collections

List all available Hadith collections.

get_recitation_url

Obtain an audio URL for a verse recitation from a chosen reciter.

list_reciters

List all available Quran reciters.

get_surah_info

Get information about a Surah.

list_surahs

List all 114 Surahs with basic information.

list_translations

List all available Quran translations.

get_cache_stats

Retrieve cache statistics for monitoring performance.