Skip to content

Connect Gemini CLI to the Islamic texts MCP server

Add the Quran Gallery MCP server to Gemini CLI with one command or settings.json: classical Arabic books, printed-page citations, no key needed.

On this page

No account, no sign-in, no key. One command:

gemini mcp add --transport http quran-gallery https://qurangallery.com/mcp/shamela

Steps

  1. Run the command above inside your project folder. It writes the server to .gemini/settings.json in that folder. Add --scope user to write it to ~/.gemini/settings.json, so it works in every project.

  2. Run gemini mcp list. quran-gallery should show as Connected.

    A terminal: gemini mcp add writes the server to .gemini/settings.json, and gemini mcp list shows quran-gallery as Connected.

  3. Start gemini and ask a question that needs a text (below). Gemini CLI asks before each tool call the first time. Approve it.

The answer gives the edition, volume and printed page, and a link to the page in the Maktabah reader. The link has the form https://qurangallery.com/maktabah/book/{bookId}/{pageId}, for example qurangallery.com/maktabah/book/1681/10 for Sahih al-Bukhari, so it opens the page on Quran Gallery:

A terminal: gemini answers with Sahih al-Bukhari, Sultaniyya edition, volume 1 page 6, with a link to the page.

To remove it: gemini mcp remove quran-gallery.

Or edit settings.json yourself

Add the server to ~/.gemini/settings.json (all projects) or .gemini/settings.json (one project):

{
	"mcpServers": {
		"quran-gallery": {
			"url": "https://qurangallery.com/mcp/shamela",
			"type": "http"
		}
	}
}

This is what the command writes. "httpUrl": "https://qurangallery.com/mcp/shamela" works too. Keep "type": "http" next to url, because older Gemini CLI versions read a bare url as an SSE endpoint.

First prompt to try

Find the hadith «إنما الأعمال بالنيات» in the primary collections and tell me which book, edition, volume and page it is printed on. Quote the Arabic exactly.

Your assistant should call shamela_search_library (or search then fetch). The hits include صحيح البخاري, ط السلطانية, page 1/6, with a link to that page in the Maktabah reader. If it answers from memory instead, say: “Use the Quran Gallery library tool and quote what it returns.”

Search queries must be in Arabic; your assistant translates English terms first (details). Ready-made prompts for takhrīj, citing a passage and comparing tafsir are listed in the full tool surface.

Troubleshooting

  • 400, “schema at properties.transmission.items.items must be a boolean or an object”. An earlier version of our server sent a tool schema the Gemini API rejected, and every prompt failed with this error. It is fixed. Restart gemini.
  • 429, “Keyless limit reached”. Keyless use allows 10 tool calls a minute and 200 a day per IP address. Wait for the Retry-After header, or add a free key (below). See Limits and errors.
  • 503. The server or the library behind it is briefly unavailable. Retry after the Retry-After header. If the client lists zero tools, wait a minute and reconnect.
  • The tools do not appear, or a tool you expect is missing. Restart gemini and run /mcp list. The tool list is read at startup.
  • gemini mcp list shows the server as Disabled, or “Gemini CLI is not running in a trusted directory”. Gemini CLI switches off MCP servers in a folder you have not trusted, and gemini mcp remove cannot find them there either. Open gemini once in that folder and trust it. In a script or with -p, you can pass --skip-trust instead.
  • Connection fails immediately. The endpoint is /mcp/shamela. The bare /mcp is a web page, not the server.

Optional: a free key for higher limits

A key is never required. A free key raises the limit to 60 calls a minute and lifts the keyless page-range caps. Create one on the Developers page of your Quran Gallery account (how keys work), then send it as a bearer token.

Add it with --header (or -H):

gemini mcp add --transport http quran-gallery 
  https://qurangallery.com/mcp/shamela 
  --header "Authorization: Bearer qg_sk_your_key_here"

In settings.json, the same key goes in a headers object next to url:

{
	"mcpServers": {
		"quran-gallery": {
			"url": "https://qurangallery.com/mcp/shamela",
			"type": "http",
			"headers": { "Authorization": "Bearer qg_sk_your_key_here" }
		}
	}
}

Keep the key out of any settings file you commit.

Next steps

Edit this page on GitHub