Skip to content

Connect an AI to the Shamela library: 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.

On this page

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 useWhere the URL goesGuide
ChatGPTPlugins → Add → Add custom MCP server, Authentication No authenticationStep by step, with screenshots
Claude (claude.ai, Claude Desktop)Settings → Connectors → + Add → Add custom connectorStep by step, with screenshots
Claude CodeOne terminal commandClaude Code
Gemini CLIOne terminal commandGemini CLI
Cursor~/.cursor/mcp.jsonCursor
VS Code, GitHub Copilot.vscode/mcp.jsonVS Code, Copilot

ChatGPT: open ChatGPT 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.

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.

Claude Code (details):

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

Gemini CLI (details):

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

Cursor (details) — in ~/.cursor/mcp.json:

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

VS Code and GitHub Copilot (VS Code, Copilot) — in .vscode/mcp.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). If you need the config file, run it through the mcp-remote bridge, which needs Node.js:

{
	"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). If it lists none, the server could not be reached — see Limits and errors.

You can also check by hand:

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

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

Or with Claude Code:

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.

Next steps

Questions

How do I connect an AI assistant to the Shamela library?

Paste https://qurangallery.com/mcp/shamela into any app that accepts a remote MCP server, such as ChatGPT, Claude, Claude Code, Gemini CLI, Cursor, VS Code or GitHub Copilot, then ask a question that needs a text.

Do I need an account or an API key?

No. A free key is optional and raises the limit to 60 calls a minute when you need more.

How do I add the server to ChatGPT?

Open ChatGPT Plugins, choose Add then Add custom MCP server, name it Quran Gallery, paste the URL and set Authentication to No authentication.

How do I add the server to Claude?

Open Settings, then Connectors, choose Add then Add custom connector, name it Quran Gallery, paste the URL, keep No sign-in, and click Add then Connect.

How do I check the connection works?

Your client should list 15 tools, starting with shamela_search_library. Ask for a hadith in the primary collections and the answer should name a book, a printing and a page.

Why does my assistant answer from memory?

Tell it directly: use the Quran Gallery library tool and quote the printed page it returns.

What are the free limits?

Without a key, 10 tool calls a minute and 200 a day per IP address. With a free key, 60 a minute and no daily cap.

Edit this page on GitHub