# MCP for developers: Connect an AI to the Shamela library: getting started

Source: https://qurangallery.com/docs/mcp/getting-started

> Add the Quran Gallery MCP server to ChatGPT, Claude, Cursor, VS Code or Gemini CLI by URL. No account or key needed. Run your first cited search.

Paste one URL into your assistant and ask a question. No account and no key are needed to start; a free key raises the limits when you need more.

## 1. Add the server

The server speaks MCP over **streamable HTTP** at:

```
https://qurangallery.com/mcp/shamela
```

That URL is all a client needs. The text behind it is the Maktabah al-Shamela library (8,594 works); Quran Gallery runs this server, and shamela.ws does not. Where you paste it depends on the app:

| You use                            | Where the URL goes                                                              | Guide                                       |
| ---------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------- |
| ChatGPT                            | Plugins → **Add → Add custom MCP server**, Authentication **No authentication** | [Step by step, with screenshots](https://qurangallery.com/docs/mcp/chatgpt) |
| Claude (claude.ai, Claude Desktop) | Settings → Connectors → **+ Add → Add custom connector**                        | [Step by step, with screenshots](https://qurangallery.com/docs/mcp/claude)  |
| Claude Code                        | One terminal command                                                            | [Claude Code](https://qurangallery.com/docs/mcp/claude-code)                |
| Gemini CLI                         | One terminal command                                                            | [Gemini CLI](https://qurangallery.com/docs/mcp/gemini-cli)                  |
| Cursor                             | `~/.cursor/mcp.json`                                                            | [Cursor](https://qurangallery.com/docs/mcp/cursor)                          |
| VS Code, GitHub Copilot            | `.vscode/mcp.json`                                                              | [VS Code](https://qurangallery.com/docs/mcp/vscode), [Copilot](https://qurangallery.com/docs/mcp/copilot)   |

**ChatGPT**: open [ChatGPT Plugins](https://chatgpt.com/plugins), click **Add → Add custom MCP server**, name it _Quran Gallery_ and paste the URL. Set Authentication to **No authentication**, because it starts on OAuth and fails there. Tick _I understand and want to continue_, click **Create as a plugin**, then **Connect**. Older accounts use **Settings → Apps & Connectors → Advanced settings → Developer mode → Create**. [Step by step](https://qurangallery.com/docs/mcp/chatgpt).

**Claude** (claude.ai and Claude Desktop): open **Settings → Connectors** (some versions: **Customize → Connectors**), click **+ Add → Add custom connector**, name it _Quran Gallery_, paste the URL and click **Continue**. Keep **No sign-in**, click **Add**, then **Connect**. Switch it on for a chat from **+ → Connectors**. [Step by step](https://qurangallery.com/docs/mcp/claude).

**Claude Code** ([details](https://qurangallery.com/docs/mcp/claude-code)):

```bash
claude mcp add --transport http quran-gallery https://qurangallery.com/mcp/shamela
```

**Gemini CLI** ([details](https://qurangallery.com/docs/mcp/gemini-cli)):

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

**Cursor** ([details](https://qurangallery.com/docs/mcp/cursor)) — in `~/.cursor/mcp.json`:

```json
{
	"mcpServers": {
		"quran-gallery": { "url": "https://qurangallery.com/mcp/shamela" }
	}
}
```

**VS Code** and **GitHub Copilot** ([VS Code](https://qurangallery.com/docs/mcp/vscode), [Copilot](https://qurangallery.com/docs/mcp/copilot)) — in `.vscode/mcp.json`:

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

**Claude Desktop config file**: Claude Desktop does not connect to a remote server written into `claude_desktop_config.json` as a `"url"` entry, so a config copied from the Cursor block above fails there. Add the server under **Settings → Connectors** instead ([Claude](https://qurangallery.com/docs/mcp/claude)). If you need the config file, run it through the `mcp-remote` bridge, which needs Node.js:

```json
{
	"mcpServers": {
		"quran-gallery": {
			"command": "npx",
			"args": ["-y", "mcp-remote", "https://qurangallery.com/mcp/shamela"]
		}
	}
}
```

Save the file and restart Claude Desktop.

Menu names move between releases. If yours differ, look for _connectors_, _integrations_ or _MCP servers_ in the client's settings — any client that accepts a remote MCP URL works.

> Use the full path, `/mcp/shamela`. The bare `/mcp` is the page describing the server, not the endpoint, and pointing a client at it will not work.

## 2. Ask something

Restart your client if it asks you to, then ask a question that needs a text:

> _Find the hadith "إنما الأعمال بالنيات" in the primary collections and tell me exactly which printed page it's on._

Your assistant should call `shamela_search_library`, and the answer should name a book, a printing, and a page — for that hadith, **صحيح البخاري, ط السلطانية, page 1/6**.

If it answers from memory instead of calling the tool, say so directly: _"Use the Quran Gallery library tool and quote the printed page it returns."_

## 3. Check the connection

Your client should list 15 tools, starting with `shamela_search_library` (see [the full tool surface](https://qurangallery.com/docs/mcp/tools)). If it lists none, the server could not be reached — see [Limits and errors](https://qurangallery.com/docs/mcp/limits-and-errors).

You can also check by hand:

```bash
curl -X POST https://qurangallery.com/mcp/shamela \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

It returns a JSON object listing the tools, `shamela_search_library` first. Without a key, listing tools does not spend your tool-call allowance.

## 4. Optional: add a key for higher limits

Without a key you get **10 tool calls a minute and 200 a day** per IP address, and the two page-range readers return a few pages per call (see [Limits and errors](https://qurangallery.com/docs/mcp/limits-and-errors)). That covers trying the server and occasional lookups. For research sessions, or anything you build on it, a free key is available: **60 calls a minute**, no daily cap, full page ranges. Skip this section until you hit a limit.

Sign in to your Quran Gallery account, go to **Developers**, and create a key with a descriptive name.

The full key is shown **once**, on creation. Copy it then — only the first few characters are visible afterwards. Keys look like this:

```
qg_sk_ghjKm4x…
```

`sk` stands for _secret key_. Treat it exactly like a password: it authenticates as **you**, it belongs in a password manager or a secret store, and it must never be committed to git or pasted into a public issue.

Send it as a bearer token on every request. In a config file:

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

Or with Claude Code:

```bash
claude mcp add --transport http quran-gallery \
  https://qurangallery.com/mcp/shamela \
  --header "Authorization: Bearer qg_sk_your_key_here"
```

The key travels only in `Authorization: Bearer …` — no query parameter, no OAuth flow. A client that accepts only a bare URL stays on the keyless limits.

> Full details on creating, rotating and revoking keys are in [API keys](https://qurangallery.com/docs/accounts/api-keys).

## Next steps

- [Open Quran Gallery MCP](https://qurangallery.com/mcp)
- [Islamic MCP servers compared: Shamela, hadith and Quran](https://qurangallery.com/docs/mcp/islamic-mcp-servers-compared)
- [Connect ChatGPT to the Shamela library](https://qurangallery.com/docs/mcp/chatgpt)
- [MCP server for Islamic texts: what it does](https://qurangallery.com/docs/mcp/overview)
