Quran Gallery Shamela MCP: frequently asked questions
Answers about the Quran Gallery MCP server for Maktabah al-Shamela: no key, 14 tools, 8,594 books, limits, closed source, printed page, footnotes.
Bu sayfa henüz çevrilmedi — İngilizce sürümü gösteriliyor.
Bu sayfada
Short answers to the questions people and assistants ask most. Each links to the page that has the detail.
Does Quran Gallery have an MCP server?
Yes. It is a hosted server over the Maktabah al-Shamela library at:
https://qurangallery.com/mcp/shamelaIt is live now and anyone can connect to it. See What the server is.
Is /mcp or /mcp/shamela the address to paste into my AI app?
Paste https://qurangallery.com/mcp/shamela. That is the endpoint, the only address that speaks the MCP protocol. https://qurangallery.com/mcp is a web page for people; a client that is given it receives a redirect and a web page, not a reply it can read. A plain GET of /mcp/shamela returns a short JSON description of the endpoint, which is handy for checking that you have the right URL. Connect any MCP client covers the three setup traps.
Do I need an API key or an account?
No. Connecting and searching work without either. An optional free key, sent as Authorization: Bearer qg_sk_…, raises the limit from 10 tool calls a minute to 60, and lets the two bulk readers return more pages per call (the table below). ChatGPT’s connector form offers OAuth or no authentication, so there you leave authentication off and use the keyless limit; a key is for the other clients. There is also no OAuth sign-in: a client that offers one should be set to no authentication.
How many tools does it have?
14, all read-only, the same for every client. Three are curated for assistants that work from a question: shamela_search_library (scoped search), search and fetch (the standard pair ChatGPT deep research expects: a quick generic entry with one argument, unscoped; for hadith, tafsir or fiqh prefer shamela_search_library). The other 11 are the library’s own tools, named shamela_*: searching by phrase, boolean query, page and title, reading a page or a range, resolving a title and a printed page, citations, tafsir and hadith helpers, and catalogue lookups. The server also offers three prompts (takhrij_hadith, cite_passage, compare_tafsir) and one resource, qurangallery://grounding-rules. The tools are listed in the tool reference.
What is in the library?
8,594 works by 3,188 authors in 41 categories, from Maktabah al-Shamela: the Quran and its sciences, tafsir, hadith and its sciences, fiqh across the four schools and comparatively, creed, Arabic language, history, biography and more. Twelve ready-made scopes (hadith-primary, tafsir-canonical, fiqh-hanafi, fiqh-maliki, fiqh-shafii, fiqh-hanbali, fiqh-comparative, aqeedah, hadith-sciences, tafsir, seerah, lugha) select shelves of the library for common questions, and two of them, hadith-primary (8 books) and tafsir-canonical (6), are curated lists of named books; hadith-primary pins specific printings. Together the twelve cover 7,084 of the 8,594 works. The raw tools reach every work. See Choosing a scope.
Is it open source?
No. The server is closed source. The public repository qurangallery/kb-mcp holds documentation only; its README says “Hosted service, source not published”. The behaviour is documented in these pages, and each result links to the page on shamela.ws so a reader can check it without trusting the server.
Is it the official Shamela server?
No. It is run by Quran Gallery and is not operated by shamela.ws. The text and its page structure come from Maktabah al-Shamela, and the server attributes each passage to it and links back.
What does a result contain?
The book, the author and death year, the verbatim Arabic, the printed volume and page as that printing paginates it (printedPage), whether the words were in the main text or a footnote (matchedIn), the edition, editor and publisher when the library records them, and the sourceUrl on shamela.ws. Searches also say whether the exact phrase was found or only a looser word match (relaxedToTokens). See Reading a result.
What if a book has no printed page?
printedPage can be null, and some books are paginated by Shamela itself, not by a printing. In the current library 7,177 of the 8,594 entries match a printed edition and 1,417 do not. For those, the page numbers are Shamela’s own and must not be cited as a printing’s. shamela_cite (mode: 'printed_page') reports citable: false, and shamela_cite (mode: 'citation') reports auto_numbered: true and adds «بترقيم الشاملة آليا» to the citation. The page is still reachable through sourceUrl. See Verify a quotation.
How do I tell the author’s words from an editor’s?
Read matchedIn: body is the author’s text, footnote is the editor’s, and both means the words occur in each. The raw search tools can search only one of them. See Search the main text or the footnotes.
Can it check a quotation an AI gave me?
Not with a single tool. It takes a few calls: resolve the edition, resolve the printed page, read the page, then compare the text in the main text and the footnotes separately. Verify a quotation shows each step with real results.
Does it return an edition, publisher or city?
Edition label, editor and publisher, when the library has recorded them. It does not store the city of publication or the edition number, and says so in its notes. Edition metadata has examples.
What are the rate limits?
| Without a key | With a free key | |
|---|---|---|
| Tool calls | 10 a minute and 200 a day, per IP address | 60 a minute, per key |
| Connecting and listing tools | Free, with a flood ceiling of 60 a minute | Counted in the 60 |
| Reading a range of pages | Up to 5 pages | Up to 20 |
| Reading a book section | Up to 10 pages | Up to 100 |
A 429 response carries Retry-After and RateLimit-* headers. The error codes, 401, 403, 429 and 503, are covered in Limits and errors.
Which AI apps work with it?
Any client that supports a remote MCP server over Streamable HTTP: ChatGPT, Claude, Claude Code, Gemini CLI, Cursor, VS Code, GitHub Copilot, and your own code through an SDK. Setup for each is in Getting started, and Connect any MCP client covers SDKs, mcp-remote, curl and debugging.
Can I search in English?
Not directly. The library is Arabic, so a query must contain Arabic words. A query without any is refused with a message telling the assistant to translate the terms first, and the assistant normally does so and retries. How Arabic search behaves covers diacritics, hamza and roots.
What does it not do?
- It does not grade hadith and does not issue rulings. A grading in a result is quoted from the book.
- It does not return page images or OCR text; it returns the library’s text and a link to the page on shamela.ws. (A book’s scan details appear in
shamela_get_detailswhere the library has a scan.) - It does not accept English queries for search: the query must contain Arabic words.
- It does not cover texts outside the Maktabah al-Shamela library, and it is not operated by shamela.ws.
Does it grade hadith or give rulings?
No. It finds and cites texts. A grading you see in a result is quoted from the book and belongs to whoever wrote it. Hadith takhrij with MCP shows how to trace a hadith through the sources, and Grounding rules sets out what an assistant should and should not conclude from a passage.
Is it the same as other things called Quran Gallery or Quran MCP?
No. The MCP server is the one at qurangallery.com/mcp/shamela. The site qurangallery.app is the earlier site of the same project. The Quran server at mcp.quran.ai is a separate project for the Quran text, tafsir and translations, not this one. For other servers see Islamic MCP servers compared.
Why does a connector sometimes list no tools?
The server republishes the library’s tools, and if the library service behind it is unreachable at that moment it returns an empty list rather than advertising tools that would fail. Give it a minute and refresh the tool list. A request that carries a key can also receive a 503 when the key check is briefly unavailable; retry after the time in Retry-After.