Skip to main content
Glama

qul-mcp

An MCP server and agent skill for the Quranic Universal Library (QUL) by Tarteel. It gives Claude and other MCP clients Quran text, translations, tafsir, word-by-word data and recitation audio, for two jobs:

  • Building apps with Islamic content. Coding agents look up real resource IDs, response shapes, fonts and recitations with ayah timings while they build, instead of guessing them or typing Quran text from memory.

  • Answering questions. Assistants quote ayahs, translations and tafsir exactly as QUL returns them, and name the source.

It is read-only and needs no API key. It calls QUL's public JSON API at https://qul.tarteel.ai/api/v1.

Not an official Tarteel project. QUL's docs still list its public API as "coming soon", so endpoints may change. The full datasets (JSON/SQLite) are at https://qul.tarteel.ai/resources and need a free account.

Tools

Tool

What it does

qul_list_chapters

All 114 surahs with names, verse counts, revelation place

qul_get_chapter

Details for one surah

qul_get_verses

Arabic text of an ayah or range in any of 14 scripts, with optional translations and word-by-word meanings

qul_list_resources

Find IDs for translations, tafsirs, languages and recitations

qul_get_translations

One translation over a passage, or compare many translations of one ayah

qul_get_tafsir

Tafsir for an ayah or range, as plain text or HTML. Never truncated: long tafsir comes in numbered parts

qul_get_audio

Audio URLs for a surah or ayah recitation

qul_get_ayah_timings

Start/end time of each ayah inside a surah's audio file

qul_random_ayah

A random ayah with a translation or tafsir

Ayahs are identified as "chapter:verse", e.g. "2:255".

Related MCP server: quran-mcp

Install

Requires Node.js 20+.

git clone https://github.com/kzroo/qul-mcp.git
cd qul-mcp
npm install        # also builds dist/

Claude Code

claude mcp add qul -- node /absolute/path/to/qul-mcp/dist/index.js

Optionally install the skill, which tells Claude when to use these tools and how to quote Quran content responsibly:

mkdir -p ~/.claude/skills && cp -r skills/qul ~/.claude/skills/

Claude Desktop and other MCP clients

{
  "mcpServers": {
    "qul": {
      "command": "node",
      "args": ["/absolute/path/to/qul-mcp/dist/index.js"]
    }
  }
}

Long tafsir is split into parts of about 30,000 characters so each response fits within MCP clients' output limits (Claude Code's default is 25,000 tokens). Set QUL_PART_CHARS to change the size.

Set QUL_API_BASE_URL to point at another QUL instance, for example a local one at http://localhost:3000/api/v1.

Development

npm run build       # compile to dist/
npm test            # unit tests
npm run test:live   # end-to-end tests against qul.tarteel.ai

Notes on the QUL API

  • The verses and segments endpoints paginate. QUL computes the page size as [per_page | 10, 286].min. That is a bitwise OR, so per_page=5 returns 15 rows and per_page=50 returns 58. This server picks page sizes that come through unchanged and follows next_page.

  • Some translations (e.g. 131, The Clear Quran) are not available from /translations/{id}/by_range but do appear when attached to verses with translations=131.

License

MIT. Quran data comes from QUL; check each resource's license on https://qul.tarteel.ai/resources before redistributing it.

Available Tools

9 tools
qul_get_audioGet recitation audioA
Read-only

Get audio URLs for a recitation. For a surah_recitation pass chapter; for an ayah_recitation pass chapter and optionally ayah. Find recitation IDs with qul_list_resources.

Inputs: kind (required), chapter (required), recitation_id (required), ayah.

qul_get_ayah_timingsGet ayah timingsA
Read-only

Get start/end times (milliseconds) of each ayah inside a surah recitation's audio file, for syncing text with audio. Only works for surah_recitations with has_segments=true.

Inputs: chapter (required), recitation_id (required), to_ayah, from_ayah, +1 more.

qul_get_chapterGet surah infoA
Read-only

Get details for one surah: names, verse count, revelation place and order, mushaf page range.

Inputs: chapter (required), locale.

qul_get_tafsirGet tafsirA
Read-only

Get tafsir (commentary) for an ayah. Pass resource_id for one tafsir (optionally over a range), or omit it to get several tafsirs for one ayah. Tafsir entries often cover a group of ayahs; see the verses field. Text is always complete: long tafsir comes in numbered parts, and the response's next.call says how to get the next one.

Inputs: from (required), to, part, limit, +4 more.

qul_get_translationsGet translationsA
Read-only

Get translations from one translation for a range of ayahs, or from several translations for one ayah. Pass resource_id with from/to for a passage, or omit resource_id to compare translations of a single ayah.

Inputs: from (required), to, limit, language, +3 more.

qul_get_versesGet ayahsA
Read-only

Get the Arabic text of one ayah or a range inside a surah, optionally with translations and word-by-word data. For a single ayah pass the same key as from and to, e.g. from "2:255".

Inputs: from (required), to, scripts, metadata, +5 more.

qul_list_chaptersList surahsA
Read-only

List all 114 surahs with Arabic and transliterated names, translated name, verse count and revelation place.

Inputs: locale.

qul_list_resourcesList QUL resourcesA
Read-only

List available translations, tafsirs, languages, or recitations, with the IDs other tools take. Use language and query to narrow the list; translations alone number about 200.

Inputs: type (required), limit, query, language.

qul_random_ayahRandom ayahA
Read-only

Pick a random ayah and return one translation or tafsir of it, optionally within one surah.

Inputs: type, chapter, language, text_format, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool targets a fairly distinct resource: chapters, verses, translations, tafsir, audio, timings, resource listings, and a random ayah. The main soft overlap is between qul_get_verses (which can include translations and word-by-word data) and qul_get_translations, plus qul_get_tafsir vs. verse text, but the descriptions explicitly steer usage (ranges/multi-translation compare vs. single ayah fetch).

    Naming Consistency4/5

    All tools share the qul_ prefix and a consistent verb_noun pattern (list_chapters, get_chapter, get_verses, get_tafsir, etc.). The only deviation is qul_random_ayah, which omits the verb but remains clear and readable.

    Tool Count5/5

    Nine tools is well within the sweet spot and each earns its place: listing, fetching, audio, timings, tafsir, translations, and discovery of resource IDs. No obviously redundant or trivial entries.

    Completeness4/5

    The surface covers the core Quran domain: chapters, verses (with translations and word data), tafsir, audio, ayah timings, resource discovery, and a random-ayah convenience tool. The notable gap is a text/search tool (e.g., searching verses by keyword), which agents would otherwise have to emulate client-side.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides AI assistants with comprehensive access to Islamic resources including Quran verses with translations, Tafsir commentary, Hadith collections, and audio recitations. Enables users to explore Islamic texts, get daily inspiration, and access scholarly interpretations through natural language queries.
      18
      28 npm
      10
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI clients with fast, hallucination-free access to the Quran through 13 MCP tools, covering search, navigation, morphology, tafsir, translations, and surah background over stdio and Streamable HTTP.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to retrieve canonical Quran text, translations, scholarly tafsir, full-text search, and word-level morphology from verified Quran data.
      -