Read Quran Today

Read Quran Today — the Madinah Mushaf on the web, page for page,

with recitation that highlights each word as it is read.

Features

Reading

• The Madinah Mushaf page by page, 15 lines to a page, at one type size throughout
• One page at a time, or two facing as the mushaf opens on wide screens
• Zoom and a magnifier, full screen, three text weights, a page dimmer
• A running head on every page: juz, surah and page number

Listening

• Four reciters in five recordings, with each word highlighted as it is recited
• The word being recited spelled out in Latin letters (transliteration), with its meaning beneath, in the chosen translation's language where it has one word by word (Urdu, Indonesian, Bengali, Turkish, Persian, Hindi) and in English otherwise
• The meaning of each ayah in a window that keeps up with the recitation, moved and sized as the reader likes: 127 translations in 88 languages, and the Tafsir al-Muyassar; each credited, with a link to its source
• Find a translation by typing: a language in Arabic, English or its own name, or a translator; the first time, the language of the reader's country (or device) is chosen
• Start from any word, change the speed, and repeat an ayah, a range or the whole surah, a set number of times or without end
• Download a recitation to keep

Finding your place

• An index of the 114 surahs and 30 juz, searchable by name or number
• Search the text of the Quran by its words, with or without diacritics
• A page for every surah (/surah/N/) and every juz (/juz/N/), and a plain text version of each surah for screen readers and search engines
• Picks up at the last page read; saved pages, with no account

Everywhere

• Phones, tablets and desktops; swipe, keyboard shortcuts or the on-screen buttons
• Offline reading (the whole mushaf, about 95 MB, asked before it is saved or removed), installable, dark and light
• The site in 14 languages: Arabic, English, Urdu, Indonesian, Bengali, Turkish, French, Persian, Hindi, Malay, Spanish, Russian, German and Chinese, chosen in Settings or from the browser's language; Urdu and Persian read right to left. Picking a language in Settings picks its translation in the meaning window too, and the word-by-word meanings where there are some
• Report an issue or a suggestion from inside the site
• No third-party requests and no cookies; visits counted with self-hosted Umami

Run it

npm install
npm run setup     # page fonts (~140 MB) and the page layout, one-off and resumable
npm start         # http://localhost:3000

Or run a copy of the site with Docker:

docker run -p 8080:80 ahmadanbarje/quran

DOCKER.md covers building it for your own domain.

Where things are

The data

The layout comes from api.quran.com and is checked against Tanzil and alquran.cloud; the word timings come from QUL. Recordings are served from audio.readqurantoday.com. docs/data.md explains how the pages, headers and Basmalahs are laid out.

For developers and AI assistants

MCP. https://readqurantoday.com/mcp is a public, read-only Model Context Protocol server, listed in the MCP Registry as com.readqurantoday/quran. No key; 60 requests a minute an address, 50 ayahs a call.

• Claude: Settings → Connectors → Add custom connector, with the URL above and no sign-in
• Claude Code: claude mcp add --transport http read-quran-today https://readqurantoday.com/mcp
• Gemini CLI: gemini mcp add --transport http read-quran-today https://readqurantoday.com/mcp
• VS Code: in .vscode/mcp.json, {"servers": {"read-quran-today": {"type": "http", "url": "https://readqurantoday.com/mcp"}}}
• Anything else that speaks Streamable HTTP, or your own code

Every ayah in an answer links to its own page on the site (link) and to the reader opened at it, to read in the mushaf and listen (read).

The same data by address, for clients that read resources: quran://surah/{surah}, quran://translation/{id}/{surah}, quran://tafsir/{surah}, quran://recitation/{reciter}/{surah}. A translation or reciter added to the site is offered there with no change to the server.

Plain JSON. Everything the reader loads is a static file, free to fetch: /data/surahs.json, /data/translations.json and /data/translation/<id>/<surah>.json, /data/tafsir/muyassar/<surah>.json, /data/recitations.json and /surah/<n>/<nnn>.<reciter>.timing.json. Please credit the translators and link back.

Build and test

The layout audit renders all 604 pages at a chosen screen size: start the server and open http://localhost:3000/tests/audit.html. docs/testing.md has what each check proves.

Deploying

A static site behind nginx with no server side. Pushing to main runs the checks; a green run moves the release branch, and the server pulls it within a minute and clears Cloudflare's copy of the pages. DEPLOY.md has the setup.

More

• docs/typesetting.md — page fonts, and how the type is sized
• docs/data.md — how the layout is built
• docs/speed.md — what loads and when
• docs/testing.md — the checks, and how the marks are verified
• docs/fonts.md — what lives in public/fonts/

Credits

The mushaf typefaces are by the King Fahd Glorious Quran Printing Complex. Page layout from Quran.com; reference texts from Tanzil and alquran.cloud; word timings from QUL by Tarteel. The translations are from QuranEnc, the Encyclopedia of the Noble Quran, each credited to its translator or publisher as QuranEnc credits it. Saheeh International, the languages QuranEnc lacks (Amazigh, Czech, Divehi, Norwegian, Polish, Sindhi, Tatar) and the King Fahd Complex's Tafsir al-Muyassar are from Tanzil. The words' English is Quran.com's word-by-word data. The code is MIT.