quran-kemenag-mcp

# Quran Kemenag MCP MCP server for querying literal Qur'an data from the same Kemenag web API used by: ```text 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 ```bash npm install npm run build ``` ## Run Stdio transport, for local MCP clients that launch the server process: ```bash npm start ``` Native Streamable HTTP transport, for remote MCP clients such as ChatGPT Developer Mode: ```bash 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: ```bash 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: ```bash npm run start:http ngrok http 3000 ``` Then configure ChatGPT Developer Mode with: ```text https://<your-ngrok-domain>/mcp ``` ## MCP Client Config Use an absolute path to this repo: ```json { "mcpServers": { "quran-kemenag": { "command": "node", "args": ["/home/matahari/code/quran-kemenag-mcp/dist/index.js"] } } } ``` ## Example Prompt ```text Use quran-kemenag to get surah 17 ayah 1 from Quran Kemenag. ``` ## Development ```bash 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`