Skip to content

Add the Islamic library MCP server to VS Code

Add the Quran Gallery MCP server to VS Code with mcp.json, no key needed, and search classical Arabic books with printed-page citations in chat.

On this page

No account, no sign-in, no key. VS Code reads MCP servers from an mcp.json file.

Steps

  1. In your workspace, create .vscode/mcp.json. (Or run MCP: Add Server from the Command Palette and follow the guided flow, choosing the HTTP type and the URL below.)
  2. Add the server:
{
	"servers": {
		"quran-gallery": { "type": "http", "url": "https://qurangallery.com/mcp/shamela" }
	}
}
  1. Save. VS Code shows a Start action above the server entry; start it and trust it when asked.
  2. Open the chat view in agent mode, check that quran-gallery appears in the tools list, and ask a question (below).

For the same setup through GitHub Copilot, see GitHub Copilot in VS Code. The /mcp page has a one-click VS Code install button.

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

  • 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 the server from the mcp.json editor (the inline Restart action) or run MCP: List Servers and restart it.
  • 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 a headers entry to the server:

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

Do not commit a workspace file that contains a key.

Next steps

Edit this page on GitHub