This server lets AI applications, LLM agents, and IDE assistants retrieve authentic Islamic content (Quran, Hadith, books, fatwas, articles, sermons, and audio) via MCP tools.
Fetch Quran translations and single-ayah audio via quran_services (QuranEnc).
Retrieve full Quran audio recitations and reciter/author profiles via islamhouse_quran.
Search and read Hadith texts, categories, and explanations via hadeethenc_services.
Access IslamHouse library content: books, audios, videos, fatwas, articles, authors, and translations via islamhouse_library.
Get targeted Islamic content for Muslims and non-Muslims via bayan_al_islam.
Access official Haramain fatwas, sermons, hadiths, and Quran content via risalat_al_haramain.
Fetch Al Montaka content and metadata lookups (age groups, categories, persons, tags, etc.).
Use it with stdio-based MCP clients (Claude Desktop, Cursor, VS Code, Windsurf) or programmatically with JavaScript/Python to feed context or enable agentic tool calling.
Enables Google Gemini models to access authentic Islamic content including Quran translations, Hadith details, and IslamHouse library items through MCP tools.
Enables OpenAI GPT models to access authentic Islamic content such as Quran translations, Hadith collections, and IslamHouse library items via MCP tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Islamic Content MCP Server Get the English translation of Surah Al-Fatiha."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An official Model Context Protocol (MCP) Server developed for The Association for Multi-lingual Islamic Content designed to connect AI applications, custom LLM agents, and AI assistants to authentic Islamic content (the Holy Qur'an, Hadith, and Islamic resources) in multiple languages.
This server acts as a bridge for the islamic-content-sdk, exposing its endpoints as tools and documentation as resources so that AI models can fetch live content and learn how to develop code using both the NPM (JS/TS) and PIP (Python) libraries.
NPM Package: islamic-content-sdk
PyPI Package: islamic-content-sdk
Related MCP server: quran-mcp
Quran Services: Consolidated endpoint quran_services and islamhouse_quran for translations, audio, reciters, and categories.
Hadith Services: Consolidated endpoint hadeethenc_services for categories, translations, and explanations.
IslamHouse Library: Centralized endpoint islamhouse_library for books, audios, videos, fatwas, articles, author data, and translations.
Bayan Al-Islam & Risalat Al-Haramain: Powerful endpoints bayan_al_islam and risalat_al_haramain for specialized Islamic databases, lookup tables, and targeted content lists.
This MCP server is designed primarily to connect authentic Islamic content directly to your AI applications and custom LLM workflows.
npm install islamic-content-mcp-server
# Also install your preferred LLM library (e.g., openai, @google/genai, @anthropic-ai/sdk)The easiest way is to use the built-in client to gather context programmatically and feed it to the LLM:
import { IslamicContentMCPClient } from "islamic-content-mcp-server";
import OpenAI from "openai";
// 1. Initialize and connect the client (starts the server internally via stdio)
const client = new IslamicContentMCPClient();
await client.connect();
// 2. Fetch structured context (customize these values to fit your application's user search)
const context = await client.getContext({
topic: "Prayer", // Replace with your dynamic topic (e.g., "Fasting", "Charity", "Faith")
sources: ["quran", "hadith"], // Specify sources: "quran", "hadith", or both
language: "en" // Language context: "en", "ar", etc.
});
// 3. Feed the context to your LLM
const openai = new OpenAI();
const completion = await openai.chat.completions.create({
model: "gpt-4o",
messages: [
{
role: "system",
content: `Use the following authentic context to answer the user's question:\n\n${context}`
},
{
role: "user",
content: "What does the Quran say about prayer?"
}
]
});
console.log(completion.choices[0].message.content);
// 4. Clean up
await client.disconnect();You can also pass the MCP tools directly to the LLM so it can dynamically decide when to call specific tools (e.g. searching Hadiths, loading suras, or fetching audio) to answer user prompts.
Click below to view the integration code for your preferred platform:
import { IslamicContentMCPClient } from "islamic-content-mcp-server";
import { GoogleGenAI } from '@google/genai';
// Initialize and connect the client (starts the server internally via stdio)
const client = new IslamicContentMCPClient();
await client.connect();
const tools = await client.getTools();
const geminiTools = tools.map(tool => ({
functionDeclarations: [{
name: tool.name,
description: tool.description,
parameters: tool.inputSchema
}]
}));
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const userPrompt = "Tell me a Hadith about Prayer from authentic sources.";
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: userPrompt,
config: { tools: geminiTools }
});
const functionCalls = response.functionCalls;
if (functionCalls && functionCalls.length > 0) {
const call = functionCalls[0];
const toolResult = await client.callTool(call.name, call.args);
const finalResponse = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: [
{ role: 'user', parts: [{ text: userPrompt }] },
{ role: 'model', parts: [{ functionCall: call }] },
{ role: 'user', parts: [{ functionResponse: { name: call.name, response: { content: toolResult } } }] }
]
});
console.log("Gemini response:\n", finalResponse.text);
} else {
console.log("Gemini response:\n", response.text);
}
await client.disconnect();import { IslamicContentMCPClient } from "islamic-content-mcp-server";
import OpenAI from "openai";
const client = new IslamicContentMCPClient();
await client.connect();
const tools = await client.getTools();
const openaiTools = tools.map(tool => ({
type: "function",
function: {
name: tool.name,
description: tool.description,
parameters: tool.inputSchema
}
}));
const openai = new OpenAI();
const messages = [{ role: "user", content: "Tell me the translation of Hadith number 66512 in English." }];
const response = await openai.chat.completions.create({
model: "gpt-4o",
messages,
tools: openaiTools
});
const toolCalls = response.choices[0].message.tool_calls;
if (toolCalls && toolCalls.length > 0) {
const toolCall = toolCalls[0];
const toolResult = await client.callTool(toolCall.function.name, JSON.parse(toolCall.function.arguments));
messages.push(response.choices[0].message);
messages.push({
role: "tool",
tool_call_id: toolCall.id,
content: JSON.stringify(toolResult)
});
const finalResponse = await openai.chat.completions.create({
model: "gpt-4o",
messages
});
console.log("OpenAI response:\n", finalResponse.choices[0].message.content);
} else {
console.log("OpenAI response:\n", response.choices[0].message.content);
}
await client.disconnect();import { IslamicContentMCPClient } from "islamic-content-mcp-server";
import Anthropic from "@anthropic-ai/sdk";
const client = new IslamicContentMCPClient();
await client.connect();
const tools = await client.getTools();
const claudeTools = tools.map(tool => ({
name: tool.name,
description: tool.description,
input_schema: tool.inputSchema
}));
const anthropic = new Anthropic();
const userPrompt = "Fetch the translation of Surah Al-Fatiha in English.";
const response = await anthropic.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1024,
tools: claudeTools,
messages: [{ role: "user", content: userPrompt }]
});
const toolUse = response.content.find(block => block.type === "tool_use");
if (toolUse) {
const toolResult = await client.callTool(toolUse.name, toolUse.input);
const finalResponse = await anthropic.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1024,
tools: claudeTools,
messages: [
{ role: "user", content: userPrompt },
{ role: "assistant", content: response.content },
{
role: "user",
content: [
{
type: "tool_result",
tool_use_id: toolUse.id,
content: JSON.stringify(toolResult)
}
]
}
]
});
console.log("Claude response:\n", finalResponse.content[0].text);
} else {
console.log("Claude response:\n", response.content[0].text);
}
await client.disconnect();import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
# Launches the Node server via npx on stdio
server_params = StdioServerParameters(
command="npx",
args=["-y", "islamic-content-mcp-server"]
)
async def run():
async with stdio_client(server_params) as (read_stream, write_stream):
async with ClientSession(read_stream, write_stream) as session:
# Initialize connection
await session.initialize()
# List available tools
tools = await session.list_tools()
print(f"Loaded {len(tools.tools)} tools.")
# Call tool: quranenc_translation_aya
result = await session.call_tool("quranenc_translation_aya", {
"translationKey": "english_saheeh",
"suraNumber": 1,
"ayaNumber": 1
})
print("Translation Result:")
print(result.content[0].text)
if __name__ == "__main__":
asyncio.run(run())You can load this MCP server directly into AI-powered IDEs and desktop assistants. Click below to view the configurations:
Add the server config to your Claude Desktop configuration file:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Add the following block under mcpServers:
{
"mcpServers": {
"islamic-content": {
"command": "npx",
"args": [
"-y",
"islamic-content-mcp-server"
]
}
}
}Note: Replace npx with the absolute path to npm/npx if your client cannot locate it globally.
Go to Settings > Features > MCP.
Click + Add New MCP Server.
Fill in the details:
Name: Islamic Content
Type: stdio
Command: npx -y islamic-content-mcp-server
Click Save.
Add the configuration block under mcpServers inside your MCP settings file:
Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json (or similar depending on the extension version)
macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
{
"mcpServers": {
"islamic-content": {
"command": "npx",
"args": [
"-y",
"islamic-content-mcp-server"
]
}
}
}Add the configuration block under mcpServers in your Windsurf MCP configuration file:
Path: ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"islamic-content": {
"command": "npx",
"args": [
"-y",
"islamic-content-mcp-server"
]
}
}
}Add the configuration block under mcpServers in your Antigravity configuration file:
Windows: C:\Users\<YourUsername>\.gemini\antigravity-ide\mcp_config.json
macOS: ~/.gemini/antigravity-ide/mcp_config.json
{
"mcpServers": {
"islamic-content": {
"command": "npx",
"args": [
"-y",
"islamic-content-mcp-server"
]
}
}
}To optimize for AI Context Windows and LLM Tool Calls, the server exposes 6 powerful, parameter-driven tools. Use the action parameter to select the behavior of the tool.
quran_services (QuranEnc)Fetch Quran translations and audio via QuranEnc.
Actions: list_translations, get_sura_translation, get_aya_translation, get_aya_audio
islamhouse_quranFetch Quran categories, reciters, and audio from IslamHouse.
Actions: list_categories, get_category, get_author, get_author_recitations, get_sura_details, get_sura_recitations, get_recitation_details
hadeethenc_servicesFetch Hadith categories, lists, and translations from HadeethEnc.
Actions: list_languages, list_categories, list_root_categories, list_hadiths, get_hadith_details
islamhouse_libraryAccess the IslamHouse Library for books, audios, videos, fatwas, articles, and author data.
Actions: get_types, get_categories, get_categories_tree, get_child_categories, get_category_basic, get_sub_categories, get_category_types, get_category_languages, list_items, get_author_items, get_category_items, get_latest_items, get_highlighted_items, get_items_count, get_item_details, get_item_attachments, get_item_tree, get_item_card_translations, get_item_translations, list_authors, get_author_details, get_author_card_translations, get_author_available_types, get_author_available_locales, list_languages, get_language_terms, get_language_availability
bayan_al_islamAccess Bayan Al-Islam for targeted Islamic content.
Actions: list_languages, list_muslim_content, list_non_muslim_content, get_content, list_paginated_languages, get_recent_contents, get_lookups, search_name, get_available_languages, get_content_translation, get_attachments_translation
risalat_al_haramainAccess Risalat Al-Haramain for fatwas, hadeeths, and contents.
Actions: get_full_contents, get_contents, get_content, search_name, search_contents, get_available_languages, get_content_translation, get_fatwas, get_hadeeths, get_quran, get_lookups_languages, get_lookups_content_types
al_montakaAccess Al Montaka to fetch general content and metadata lookups.
Actions: list_contents, get_comments, get_lookups_age_groups, get_lookups_categories, get_lookups_entities, get_lookups_expert_levels, get_lookups_ideologies, get_lookups_languages, get_lookups_persons, get_lookups_sections, get_lookups_tags, get_lookups_targeted_groups, get_lookups_youtube_channels
If you want to clone, modify, or run the server locally:
git clone https://github.com/2yousefreda/islamic-content-mcp.git
cd islamic-content-mcpnpm install
npm run buildnode dist/bin.jsTo configure your AI client to use your local development folder, change the config to:
"command": "node",
"args": ["/path/to/islamic-content-mcp/dist/bin.js"]You can support the projects and efforts of The Association for Multi-lingual Islamic Content through the following official channels:
This project is licensed under the ISC License.
Access Al Montaka to fetch general content. Note: Content fetching by category is currently unstable upstream, so use it to fetch the latest general content instead.
Action Mapping:
list_contents: page (int) -> Returns { data: [], meta: {} }
get_comments: id (int) -> Returns comments for content
get_lookups_age_groups, get_lookups_languages, get_lookups_targeted_groups, get_lookups_youtube_channels: No args -> Returns lookups array
get_lookups_categories, get_lookups_entities, get_lookups_expert_levels, get_lookups_sections, get_lookups_tags: languageId (int), [nameCont] -> Returns lookups array
get_lookups_ideologies: languageId (int), parentId (int), [nameCont] -> Returns lookups array
get_lookups_persons: [nameCont], [page] -> Returns lookups array
Inputs: action (required), id, page, nameCont, +2 more.
Access Bayan Al-Islam to fetch specialized Islamic content targeting Muslims and Non-Muslims, including translated articles and structured lookups. Unlike the general IslamHouse library, this provides curated content categorized by the target audience's faith perspective.
Behavior: Read-only. Idempotent. No authentication. Falls back to default language if translation is missing. Usage Guidelines:
Use when seeking content specifically tailored for non-Muslims, or curated responses to common questions.
Do NOT use for raw Hadith (use hadeethenc_services) or Quran recitations (use islamhouse_quran or quran_services).
Action Mapping:
list_languages, list_paginated_languages: language, page (int), [name] -> Returns { languages: [{ code, name }] }
list_muslim_content, list_non_muslim_content: language -> Returns { paths: [] }
get_content, search_name: id (int) or name (string), language -> Returns { id, title, body, matchingResults: [] }
get_recent_contents: ids (array of ints), init (bool), lang (overrides language) -> Returns { recentItems: [] }
get_lookups, get_available_languages: id (int), language -> Returns { metadata: [] }
get_content_translation, get_attachments_translation: id (int), targetLanguage (ISO-639-1), language -> Returns { translatedBody, attachments: [] }
Returns: Concrete JSON payload { id, title, body, paths: [], recentItems: [] } containing targeted content.
Inputs: action (required), id, ids, init, +5 more.
Access HadeethEnc to fetch authentic Hadith texts, categories, and translations in multiple languages. This is the only tool dedicated exclusively to Hadith texts and their detailed explanations.
Behavior: Read-only. Idempotent. No authentication. No strict rate limits. Returns empty if ID not found. Usage Guidelines:
Use when the user asks for Prophetic sayings, Hadith translations, or scholarly explanations.
Do NOT use for official fatwas or general books (use islamhouse_library or risalat_al_haramain).
Action Mapping:
list_languages, list_categories, list_root_categories: languageCode (ISO-639-1) -> Returns { categories: [{ id, title, hadeeths_count }] }
list_hadiths: language, categoryId (int), page (int), perPage (int) -> Returns { data: [{ id, title }] }
get_hadith_details: id (int), language (ISO-639-1) -> Returns { id, hadeeth, explanation, translations: [] }
Returns: JSON array for lists or a detailed JSON object containing specific Hadith text and translations.
Inputs: action (required), id, page, perPage, +3 more.
Access IslamHouse Library for books, audios, videos, fatwas, articles, and author metadata. Excludes Quran recitations (use 'islamhouse_quran') and Hadith texts (use 'hadeethenc_services').
Behavior: Read-only, idempotent, public access (no auth/rate limits). Cached dynamically with real-time freshness. Fallback to English on missing translations; returns empty arrays for unknown IDs; returns 400 error payload on invalid actions or malformed parameters.
Usage Guidelines:
Use for: Scholarly books, articles, fatwas, multimedia, and author biographies.
Do NOT use for: Raw Quran text/audio ('islamhouse_quran' / 'quran_services') or Hadith collections ('hadeethenc_services').
Parameters & Enums:
action: API operation (see Action Groups below).
type: Content format enum: books, audios, videos, fatwas, articles.
period: Trending window enum: daily, weekly, monthly.
sort: Ordering enum: popular, newest, oldest.
kind: Scope filter enum: main, sub.
language, siteLang, contentLang, slang, locale: 2-letter ISO-639-1 codes (e.g., 'en', 'ar').
page, limit: Integer pagination controls.
id, categoryId, authorId: Positive integer identifiers.
Action Groups & Returns:
Taxonomy (list_categories, list_types, get_categories_tree): Requires language -> Array of { id: number, name: string, parentId?: number }.
Listings (list_items, get_latest_items, get_highlighted_items): Uses page, limit, type, [categoryId/authorId/period/sort/contentLang] -> { data: ItemSummary[], total: number, page: number }.
Aggregations (get_items_count): Uses type, [categoryId/contentLang] -> { type: string, total: number }.
Details (get_item_details, get_item_attachments, get_item_translations): Requires id, [language] -> Detailed { id, title, description, attachments: Attachment[], locales: string[] }.
Authors (get_author_details, list_authors): Uses id, page, limit, [language, kind, locale, sort] -> Author profile with { id, name, biography, itemsCount: number }.
Inputs: action (required), id, kind, page, +11 more.
Access IslamHouse to fetch Quranic audio recitations, reciter (author) profiles, and Sura recitation metadata. Unlike quran_services, this specializes in high-quality, full-Sura audio recitations and reciter catalogs rather than textual translations.
Behavior: Read-only. Idempotent. No authentication. Returns 404/empty on invalid IDs, with safe fallbacks on missing audio. Usage Guidelines:
Use for full audio recitations of the Quran or reciter information (e.g., Al-Sudais).
Do NOT use for fetching written Quran text/translations (use quran_services instead).
Action Mapping:
list_categories: language (ISO-639-1) -> Category[] { id: number, title: string }
get_category, get_author: language (ISO-639-1), id (int) -> { id, title, description, count }
get_author_recitations: id (author ID, int), language (ISO-639-1) -> { data: [{ recitationId, title }] }
get_sura_recitations: suraId (int 1-114), language (ISO-639-1) -> { suraId, name, recitations: [] }
get_recitation_details: id (recitation ID, int), language (ISO-639-1) -> { id, reciterId, audioUrl, duration }
Inputs: action (required), language (required), id, suraId.
Access QuranEnc to fetch Quran textual translations, translations lists, and ayah-level audio. Unlike islamhouse_quran, this tool specializes strictly in text-based translations of meanings and single-ayah audio, rather than full recitations or reciter data.
Behavior: Read-only. Idempotent. No authentication required. No strict rate limits. Usage Guidelines:
Use this tool when you need the textual translation of an Ayah or Sura in a specific language, or a short audio clip of one Ayah.
Do NOT use this tool for full Sura recitations or fetching reciter profiles (use islamhouse_quran instead).
Action Mapping & Parameters:
list_translations: Requires language (optional localization). Returns a JSON array of available translations.
get_sura_translation: Requires translationKey and suraNumber. Returns a JSON object with the translation of the full Sura.
get_aya_translation: Requires translationKey, suraNumber, and ayaNumber. Returns a JSON object with the specific Ayah's text.
get_aya_audio: Requires translationKey, suraNumber, and ayaNumber. Returns a JSON object with an audio URL for the Ayah.
Returns: A JSON array or object containing the requested QuranEnc data.
Inputs: action (required), language, ayaNumber, suraNumber, +2 more.
Access Risalat Al-Haramain to fetch official Haramain (Two Holy Mosques) fatwas, Friday sermons, specific hadeeths, and institutional contents. Specializes in official decrees and sermons originating from Mecca and Medina, distinguishing it from general libraries.
Behavior: Read-only. Idempotent. Public endpoints have no auth. Lookup endpoints require apiKey. Handles rate limits via graceful empty returns.
Usage Guidelines:
Use for Friday sermons from the Haramain, official fatwas from Haramain scholars, or institutional news.
Do NOT use for general Islamic books (use islamhouse_library).
Action Mapping:
get_full_contents, get_contents: language, lang -> Returns { data: [{ id, title, date }] }
get_fatwas, get_hadeeths, get_quran: language, lang, [isFeatured (0/1)] -> Returns { data: [{ id, content }] }
get_content: id (int), language -> Returns { id, title, body, mediaUrls: [] }
search_contents: query (string), language -> Returns { results: [{ id, title }] }
get_lookups_languages, get_lookups_content_types: language, [apiKey] -> Returns { lookups: [] }
Returns: Concrete JSON object { data: [], lookups: [], results: [] } for Haramain official releases.
Inputs: action (required), id, lang, name, +6 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 7 tools
Most tools are separated by source and content type, but there is overlap between islamhouse_library, bayan_al_islam, and al_montaka for articles/general content, and risalat_al_haramain's get_hadeeths/get_fatwas overlap with dedicated Hadith and library fatwa tools. The detailed 'Do NOT use' guidance helps, but agents must read carefully to avoid mis-selection.
All names use lower_snake_case and are source-based, which is readable, but the pattern is inconsistent: some include domain suffixes (islamhouse_quran, quran_services, hadeethenc_services) while others are bare source names (bayan_al_islam, risalat_al_haramain, al_montaka). There is no verb_noun pattern, though this is understandable for provider-style content servers.
Seven tools is well-scoped for a multi-source Islamic content server. Each tool represents a distinct content provider or content type and earns its place without overwhelming an agent with excessive options.
The set covers the major content types for the domain: Hadith, Quran text and audio, library books/fatwas/articles, official Haramain content, and curated targeted articles. Minor gaps exist, such as no cross-source unified search and al_montaka's unstable category fetching, but agents can work around these limitations.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Connect your AI agent to 300+ methods and 100+ live tools
Search and retrieve Quran ayahs, tafsir commentary, hadith, and detailed hadith records.
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
