FarabiInnovations/mcp-quran

MCP Quran Server

A Model Context Protocol (MCP) server that provides comprehensive access to the Quran through the QuranJS API. This server enables AI assistants and applications to retrieve Quranic content including chapters, verses, translations, tafsirs, and more.

🌟 Features

• Complete Quran Access: All 114 chapters and 6,236 verses
• Multiple Retrieval Methods: By chapter, verse key, page, juz, hizb, rub
• Rich Content: Arabic text, translations, tafsirs, word-by-word breakdown
• Search Functionality: Full-text search across the Quran
• Audio Support: Recitation options and audio files
• Type Safety: Full TypeScript support with proper SDK types
• MCP Compliance: Standard Model Context Protocol implementation
• Docker Support: Easy containerized deployment

📦 Installation

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm
• Docker (optional, for containerized deployment)

Setup

Local Development

# Clone the repository
git clone https://github.com/your-username/mcp-quran.git
cd mcp-quran

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in debug mode with MCP Inspector
pnpm debug

Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# For development with hot reload
docker-compose --profile dev up -d

# Build Docker image manually
docker build -t mcp-quran .

# Run container
docker run -d --name mcp-quran-server mcp-quran

🚀 Quick Start

Basic Usage

The MCP Quran server provides tools for accessing Quranic content. Here are some examples:

Get All Chapters

{
  "name": "all_chapters",
  "arguments": {}
}

Get Verses by Chapter

{
  "name": "verses_by_chapter",
  "arguments": {
    "chapterId": 1,
    "options": {
      "language": "en",
      "translations": [131, 85],
      "words": true
    }
  }
}

Search the Quran

{
  "name": "search_quran",
  "arguments": {
    "query": "mercy",
    "options": {
      "language": "en",
      "size": 10,
      "page": 1
    }
  }
}

🛠️ Available Tools

This MCP server exposes the following tools that correspond to the QuranJS API endpoints:

📖 Chapters

• all_chapters - Get all chapters
• chapter_by_id - Get chapter by ID

📜 Verses

• verse_by_key - Get verse by chapter:verse key
• verses_by_chapter - Get verses by chapter ID
• verses_by_page - Get verses by page number
• verses_by_juz - Get verses by juz number
• verses_by_hizb - Get verses by hizb number
• verses_by_rub - Get verses by rub number
• random_verse - Get a random verse

🔍 Search

• search_quran - Search the Quran

📚 Juzs

• all_juzs - Get all juzs

📚 API Documentation

For detailed information about the available parameters, options, and response formats, please refer to the official QuranJS API documentation:

• QuranJS API Documentation - Complete API reference
• Chapters API - Chapter-related endpoints
• Verses API - Verse-related endpoints
• Search API - Search functionality
• Juzs API - Juz-related endpoints

The MCP tools follow the same parameter structure and options as the QuranJS API.

🌐 Supported Languages

The server supports multiple languages through the Language enum. See the QuranJS Language documentation for the complete list of supported languages.

🔧 Configuration

MCP Client Configuration

Add this to your MCP client configuration:

{
  "mcpServers": {
    "quran": {
      "command": "node",
      "args": ["/path/to/your/mcp-quran/build/index.js"],
      "env": {}
    }
  }
}

Docker Configuration

For Docker deployments, use the containerized version:

{
  "mcpServers": {
    "quran": {
      "command": "docker",
      "args": ["run", "--rm", "mcp-quran"],
      "env": {}
    }
  }
}

🏗️ Architecture

The server is built with:

• TypeScript: For type safety and better development experience
• Model Context Protocol SDK: For MCP compliance
• QuranJS API: For Quranic data access
• Zod: For runtime validation
• pnpm: For package management
• Docker: For containerized deployment

Project Structure

mcp-quran/
├── src/
│   ├── index.ts          # Main server entry point
│   ├── tools/            # MCP tools implementation
│   │   ├── chapters.ts   # Chapter-related tools
│   │   ├── verses.ts     # Verse-related tools
│   │   ├── search.ts     # Search functionality
│   │   └── juzs.ts       # Juz-related tools
│   └── helper/           # Helper functions
├── media/
│   └── logo.png          # Project logo
├── build/                # Compiled JavaScript
├── Dockerfile            # Docker configuration
├── docker-compose.yml    # Docker Compose setup
├── .dockerignore         # Docker ignore rules
└── package.json          # Project configuration

🧪 Development

Setup Development Environment

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in debug mode with MCP Inspector
pnpm debug

Docker Development

# Start development environment with hot reload
docker-compose --profile dev up -d

# View logs
docker-compose logs -f mcp-quran-dev

# Stop development environment
docker-compose --profile dev down

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Guidelines

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

🙏 Acknowledgments

• QuranJS API for providing the Quranic data
• Model Context Protocol for the MCP specification
• The open-source community for inspiration and support

📞 Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check the QuranJS documentation
• Review the MCP specification