Quranpedia

npm version MCP Registry smithery badge license Powered by quran-search-engine quran-search-engine

An MCP (Model Context Protocol) server that gives AI clients fast, accurate, hallucination-free access to the Quran — search, navigation, morphology, tafsir, translations, and surah background — over stdio and Streamable HTTP.

Explore the Quran through 13 MCP tools — verses, surahs, lemmas, roots, morphology, tafsir, translations, and Quranpedia encyclopedia search. Hosted at mcp.quran.us.kg. Instead of relying on an AI to "hallucinate" or predict Quranic verses, this tool routes every request to a dedicated search engine. The AI handles the natural language; the server returns the exact, literal Quranic text. Tafsir and translations come from the Quranpedia API (https://api.quranpedia.net/v1), with each answer attributed to its source.

Public endpoint

The server is publicly hosted at https://mcp.quran.us.kg/ (Cloudflare-fronted, stable). No API key, no auth — the endpoint is open and CORS-enabled for any client.

Resource	URL
MCP server (Streamable HTTP)	https://mcp.quran.us.kg/
Health check	https://mcp.quran.us.kg/health
Status page	https://quran.us.kg

Features

• 🔌 MCP compatible — Claude Desktop, Claude Web, ChatGPT, Cursor, VS Code, and others.
• 🌐 Two transports — stdio for local integrations, Streamable HTTP for remote/hosted.
• 🔍 Thirteen tools — full-text search, surah metadata, verse navigation, lemma/root lookup, morphology, plus tafsir, translations, surah background, per-ayah content options, and Quranpedia encyclopedia search.
• 📖 Accurate results — every verse comes from a verified dataset; no LLM in the loop. Tafsir and translations come from Quranpedia with a source URL attached.
• 🛡️ Hardened HTTP — host allow-list, per-IP rate limit, body cap, session reaper, /health.
• 🗄️ Offline-friendly Quranpedia cache — responses cached in memory (and optionally on disk) for 30 days.

Install

# Use the public endpoint
# → point your MCP client at https://mcp.quran.us.kg/

# Or run the server locally (stdio)
npx -y quranpedia-mcp

Documentation

Detailed docs live under docs/:

• Tools reference — every tool, its schema, response shape, and examples.
• Integrations — Claude Desktop, Claude Web, ChatGPT, Cursor, and others.
• Architecture — internals: transports, dataset loading, HTTP hardening.
• Development — build, test, add a new tool, deploy.

Quick start (HTTP)

The shortest path: use any MCP client and point it at https://mcp.quran.us.kg/. For ad-hoc testing, the integrations page shows a one-off Node snippet that uses @modelcontextprotocol/sdk directly.

Quick start (Docker)

docker compose up --build
# → "Quran MCP HTTP server listening on http://0.0.0.0:4000/"

Requirements

• Node.js 20+ (LTS recommended)
• npm, pnpm, or yarn
• Network access to api.quranpedia.net for the five Quranpedia tools (the 8 dataset tools work offline).

License

MIT — see LICENSE.

Contact

Email: [email protected]