Skip to content

Use the Islamic library MCP server with GitHub Copilot

Give GitHub Copilot agent mode in VS Code the Quran Gallery MCP server: classical Arabic books with printed-page citations, no account or key.

On this page

No account, no sign-in, no key. GitHub Copilot in VS Code uses the same MCP configuration as VS Code itself, and calls MCP tools from agent mode.

Steps

  1. Create .vscode/mcp.json in your workspace (or run MCP: Add Server from the Command Palette):
{
	"servers": {
		"quran-gallery": { "type": "http", "url": "https://qurangallery.com/mcp/shamela" }
	}
}
  1. Start the server from the Start action above its entry and trust it.
  2. Open the Copilot chat view and switch to Agent mode. Open the tools picker and confirm the quran-gallery tools are ticked.
  3. Ask a question that needs a text (below).

Organisation policy can disable MCP servers for Copilot; if the tools never appear, ask your administrator whether MCP is allowed. Full steps and key setup are on the VS Code page.

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. Open the tools picker and make sure the server is ticked; restart the server from MCP: List Servers.
  • 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. Add a headers entry exactly as shown on the VS Code page. Create one on the Developers page of your Quran Gallery account (how keys work).

Next steps

Edit this page on GitHub