# MCP for developers: Add the Islamic library MCP server to VS Code

Source: https://qurangallery.com/docs/mcp/vscode

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

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

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

3. Save. VS Code shows a **Start** action above the server entry; start it and trust it when asked.
4. 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](https://qurangallery.com/docs/mcp/copilot). The [/mcp page](https://qurangallery.com/mcp) 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](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

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

Add a `headers` entry to the server:

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

- [Open Quran Gallery MCP](https://qurangallery.com/mcp)
- [Connect Cursor to the Islamic texts MCP server](https://qurangallery.com/docs/mcp/cursor)
- [Connect Gemini CLI to the Islamic texts MCP server](https://qurangallery.com/docs/mcp/gemini-cli)
- [MCP server for Islamic texts: what it does](https://qurangallery.com/docs/mcp/overview)
