MCP 服务器

Quranpedia MCP

Provides AI clients with fast, hallucination-free access to the Quran through 13 MCP tools, covering search, navigation, morphology, tafsir, translations, and surah background over stdio and Streamable HTTP.

README

Quranpedia MCP

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