Quran Kemenag MCP

MCP server for querying literal Qur'an data from the same Kemenag web API used by:

https://quran.kemenag.go.id/quran/per-ayat/surah/17?from=1&to=1

The server uses https://web-api.qurankemenag.net with the Origin and Referer headers expected by the Kemenag web app.

Tools

get_ayahs: fetch ayah text, transliteration, Indonesian translation, footnotes, and surah metadata for a surah/range.
get_surah: fetch surah metadata.
get_tafsir: fetch Kemenag tafsir detail for an ayah id returned by get_ayahs.

Install

npm install
npm run build

Run

Stdio transport, for local MCP clients that launch the server process:

npm start

Native Streamable HTTP transport, for remote MCP clients such as ChatGPT Developer Mode:

npm run start:http

By default the HTTP server listens on port 3000 and exposes:

MCP endpoint: http://localhost:3000/mcp
health check: http://localhost:3000/health

Configuration:

PORT=8787 npm run start:http
MCP_AUTH_TOKEN=secret npm run start:http

If MCP_AUTH_TOKEN is set, requests to /mcp must include Authorization: Bearer <token>. Leave it unset when using ChatGPT's No Authentication mode.

For local ChatGPT testing, expose the HTTP server with an HTTPS tunnel and use the /mcp URL:

npm run start:http
ngrok http 3000

Then configure ChatGPT Developer Mode with:

https://<your-ngrok-domain>/mcp

MCP Client Config

Use an absolute path to this repo:

{
  "mcpServers": {
    "quran-kemenag": {
      "command": "node",
      "args": ["/home/matahari/code/quran-kemenag-mcp/dist/index.js"]
    }
  }
}

Example Prompt

Use quran-kemenag to get surah 17 ayah 1 from Quran Kemenag.

Development

npm run typecheck
npm run typecheck:test
npm test
npm run build

Notes

get_ayahs accepts:

surah: number from 1 to 114
from: first ayah number, defaults to 1
to: last ayah number, defaults to from
includeSourceUrl: whether to include the matching Kemenag page URL, defaults to true

MCP Servers