quran-mcp-server

MCP server to access Quran.com API with AI tool compatibility.

Stars

Forks

Watchers

Issues

quran-mcp-server exposes the Quran.com corpus and associated data through a Model Context Protocol (MCP) server generated from an OpenAPI specification. It provides tool endpoints for chapters, verses, translations, tafsirs, audio, languages, and more. The server is designed for seamless integration with large language models (LLMs) and AI tools, supporting both Docker and Node.js environments. Advanced logging features and flexible deployment options are included for debugging and development.

Key Features

Model Context Protocol (MCP) implementation

OpenAPI-derived endpoints for Quranic resources

Integration with Claude Desktop and AI clients

Comprehensive REST API coverage (chapters, verses, tajweed, translations, tafsirs, audio, languages)

Support for Docker and Node.js deployment

Environment variable-based configuration

Verbose logging for debugging API interactions

Authentication via API keys

Standalone or composable with other MCP servers

Automated testing support

Use Cases

Enabling AI models to answer queries about Quranic content

Providing Quranic verse lookup and search in natural language interfaces

Accessing translations and tafsir information programmatically

Embedding real-time Quranic data into chatbots or personal assistants

Offering audio recitations and reciter information through external tools

Integrating Quran.com data as a plugin in AI-powered desktop applications

Facilitating automated study tools for religious education

Allowing developers to build NLP applications on top of Quranic text data

Researching cross-linguistic access to Quranic resources

Debugging and monitoring Quranic API interactions in AI-driven workflows

README

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.

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:

bash

# 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

json

{
  "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)

json

{
  "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

json

{
  "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-server with the actual path to this repository on your system
You'll need to build the project first with npm run build or docker build -t quran-mcp-server . if using the production mode configuration
Replace your_api_key_if_needed with an actual API key if required by the Quran.com API
If you already have other MCP servers configured, add this configuration to the existing mcpServers object
After updating the configuration, restart Claude Desktop for the changes to take effect

Environment Variables

API_KEY: API key for authentication
PORT: 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

bash

# Run tests
npm test

License

This project is licensed under the MIT License.

Star History

Repository Owner

djalal

User

Repository Details

Language TypeScript

Default Branch main

Size 95 KB

Contributors 1

License MIT License

MCP Verified Sep 2, 2025

Programming Languages

TypeScript

88.7%

JavaScript

10.59%

Dockerfile

0.72%

Related MCPs

Discover similar Model Context Protocol servers

Yuque-MCP-Server

Seamless integration of Yuque knowledge base with Model-Context-Protocol for AI model context management.

Yuque-MCP-Server provides an MCP-compatible server for interacting with the Yuque knowledge base platform. It enables AI models to retrieve, manage, and analyze Yuque documents and user information through a standardized Model-Context-Protocol interface. The server supports operations such as document creation, reading, updating, deletion, advanced search, and team statistics retrieval, making it ideal for AI-powered workflows. Inspired by Figma-Context-MCP, it facilitates contextual awareness and dynamic knowledge management for AI applications.

⭐ 31
MCP
HenryHaoson/Yuque-MCP-Server

QuantConnect MCP Server

Official bridge for secure AI access to QuantConnect's algorithmic trading cloud platform

QuantConnect MCP Server enables artificial intelligence systems such as Claude and OpenAI to interface with QuantConnect's cloud platform through an official, secure, and dockerized implementation of the Model Context Protocol (MCP). It facilitates automated project management, strategy writing, backtesting, and live deployment by exposing a comprehensive suite of API tools for users with valid access credentials. As the maintained official version, it ensures security, easy deployment, and cross-platform compatibility for advanced algorithmic trading automation.

⭐ 50
MCP
QuantConnect/mcp-server

MCP Server for Iaptic

A Model Context Protocol server for accessing and managing Iaptic data with AI agents.

MCP Server for Iaptic implements the Model Context Protocol to enable AI models, such as Claude, to securely and efficiently interact with Iaptic's customer, purchase, transaction, and statistics data. The server provides a standardized interface and command set for querying and managing information related to customers, purchases, transactions, events, and application management. Designed for integration with Claude Desktop and similar AI clients, it offers both automated and manual installation options.

⭐ 5
MCP
iaptic/mcp-server-iaptic

OpsLevel MCP Server

Read-only MCP server for integrating OpsLevel data with AI tools.

OpsLevel MCP Server implements the Model Context Protocol to provide AI tools with a secure way to access and interact with OpsLevel account data. It supports read-only operations for a wide range of OpsLevel resources such as actions, campaigns, checks, components, documentation, domains, and more. The tool is compatible with popular environments including Claude Desktop and VS Code, enabling easy integration via configuration and API tokens. Installation options include Homebrew, Docker, and standalone binaries.

⭐ 8
MCP
OpsLevel/opslevel-mcp

cloudflare/mcp-server-cloudflare

Connect Cloudflare services to Model Context Protocol (MCP) clients for AI-powered management.

Cloudflare MCP Server enables integration between Cloudflare's suite of services and clients using the Model Context Protocol (MCP). It provides multiple specialized servers that allow AI models to access, analyze, and manage configurations, logs, analytics, and other features across Cloudflare's platform. Users can leverage natural language interfaces in compatible MCP clients to read data, gain insights, and perform automated actions on their Cloudflare accounts. This project aims to streamline the orchestration of security, development, monitoring, and infrastructure tasks through standardized MCP connections.

⭐ 2,919
MCP
cloudflare/mcp-server-cloudflare

mcp-server-js

Enable secure, AI-driven process automation and code execution on YepCode via Model Context Protocol.

YepCode MCP Server acts as a Model Context Protocol (MCP) server that facilitates seamless communication between AI platforms and YepCode’s workflow automation infrastructure. It allows AI assistants and clients to execute code, manage environment variables, and interact with storage through standardized tools. The server can expose YepCode processes directly as MCP tools and supports both hosted and local installations via NPX or Docker. Enterprise-grade security and real-time interaction make it suitable for integrating advanced automation into AI-powered environments.

⭐ 31
MCP
yepcode/mcp-server-js

View all Alternatives

Didn't find tool you were looking for?

Search AI Tools

quran-mcp-server

Key Features

Use Cases

README

MCP Server for Quran.com API

Overview

Endpoints

Chapters

Verses

Juzs

Search

Translations

Tafsirs

Audio

Languages

Setup

Requirements

Building the Docker Image

Claude Desktop Integration

Docker-based Production Mode

Production Mode (Node.js)

Development Mode

Environment Variables

Verbose Mode

Testing

License

Star History

Repository Owner

Repository Details

Programming Languages

Tags

Related MCPs