This MCP server exposes the Quran.com REST API (v4) via a set of tools that map to the API endpoints for chapters, verses, juzs, translations, tafsirs, audio, and languages. Clients can query for lists of chapters, specific chapters by id, verses by chapter or page, juzs, tafsirs, translations, reciters, and more, as defined in the README. Tools are designed to be consumed by LLMs or other automation clients through the MCP protocol, enabling structured tool invocations against the Quran.com corpus. To use it with Claude Desktop or similar integrations, configure the MCP server under the mcpServers section and ensure environment variables like API_KEY (if required) and VERBOSE_MODE are set according to your needs. The server supports production (Docker) and development modes depending on how you run the image or binary.

Prerequisites:

• Docker installed on your host (for production/docker-based setup)
• Optional: Node.js 22+ if choosing a Node-based run, or Python/uv if using a non-Docker path

Installation steps (Docker-based production):

1. Build or pull the Docker image (if not already built): docker pull quran-mcp-server

   or build locally if you have Dockerfile

   docker build -t quran-mcp-server .

2. Run the container in production mode: docker run -d --name quran-mcp-server -p 8000:8000 -e API_KEY=your_api_key_if_needed -e VERBOSE_MODE=true quran-mcp-server
3. Verify the server is running and responsive: curl -s http://localhost:8000/health || echo 'health check failed'

If you prefer development mode (Node/npx):

1. Install dependencies and build: npm install npm run build
2. Run in development with ts-node: npx ts-node src/server.ts
3. Ensure PORT and API_KEY environment variables are set as needed.

Prerequisites for Claude Desktop integration:

• Access to the running MCP server URL
• Knowledge of the desired environment variables (API_KEY, VERBOSE_MODE)

Note: Replace placeholders like your_api_key_if_needed with actual values as required by the Quran API.

Environment variables:

• API_KEY: API key for authentication with the Quran.com API (if required)
• PORT: Server port (default may vary by language; common choices are 8000 or 3000)
• VERBOSE_MODE: Set to 'true' to enable verbose logging of requests and responses. Useful for debugging but can be noisy in production.

Common issues:

• Docker image not found: ensure the image name matches the registry (quran-mcp-server) or build locally.
• API_KEY missing: if the API requires authentication, provide a valid key and restart the server.
• Port conflicts: ensure the chosen port is available and properly forwarded.

Configuration tips:

• When using Claude Desktop, ensure the mcpServers object contains the server-name you reference in your config.
• For development, ts-node or ts-node-dev can simplify iteration, but for production prefer the Docker image or a built binary.

Troubleshooting verbose mode:

• If VERBOSE_MODE is true, logs will include per-request tool names and arguments, responses, and potential errors with timestamps.