Skip to main content
Glama
README.md
# qul-mcp

An [MCP](https://modelcontextprotocol.io) server and agent skill for the
[Quranic Universal Library (QUL)](https://qul.tarteel.ai) 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"`.

## Install

Requires Node.js 20+.

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

### Claude Code

```sh
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:

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

### Claude Desktop and other MCP clients

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

```sh
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.

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