# MCP for developers: Connect Gemini CLI to the Islamic texts MCP server

Source: https://qurangallery.com/docs/mcp/gemini-cli

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

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

```bash
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**.

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:

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):

```json
{
	"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](https://qurangallery.com/docs/mcp/search-library)). Ready-made prompts for takhrīj, citing a passage and comparing tafsir are listed in [the full tool surface](https://qurangallery.com/docs/mcp/tools).

## 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](https://qurangallery.com/docs/mcp/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](https://qurangallery.com/docs/accounts/api-keys)), then send it as a bearer token.

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

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

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

- [Open Quran Gallery MCP](https://qurangallery.com/mcp)
- [Add the Islamic library MCP server to VS Code](https://qurangallery.com/docs/mcp/vscode)
- [Use the Islamic library MCP server with GitHub Copilot](https://qurangallery.com/docs/mcp/copilot)
- [MCP server for Islamic texts: what it does](https://qurangallery.com/docs/mcp/overview)
