Islamic Content Model Context Protocol (MCP) Server

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.

Official SDKs

• NPM Package: islamic-content-sdk
• PyPI Package: islamic-content-sdk

Features

• Quran Services: Fetch surah and ayah translations (via QuranEnc & IslamHouse Quran), retrieve MP3 audio files, and submit notes/suggestions.
• Hadith Services: Access Hadeeth listings, categories, translations, and explanations (via HadeethEnc).
• IslamHouse Library: Retrieve categorized books, audios, videos, fatwas, articles, author data, and translations in dozens of languages.
• Al-Montaka, Bayan Al-Islam & Risalat Al-Haramain: Access specialized Islamic databases, lookup tables, and targeted content lists.
• Built-in Developer Resource: Exposes a direct guide (sdk://docs/guide) to teach AI models how to write and import SDK code for both Python and TypeScript.

LLM Integration & Custom Clients (Code Integration)

This MCP server is designed primarily to connect authentic Islamic content directly to your AI applications and custom LLM workflows.

1. Install Dependencies

npm install islamic-content-mcp-server
# Also install your preferred LLM library (e.g., openai, @google/genai, @anthropic-ai/sdk)

2. Simple Integration (RAG / Context Retrieval)

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();

3. Agentic Integration (Dynamic Tool Calling)

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

Connecting to AI Desktop & IDE Clients

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.

1. Go to Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Fill in the details:
   • Name: Islamic Content
   • Type: stdio
   • Command: npx -y islamic-content-mcp-server
4. 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"
      ]
    }
  }
}

Available Tools

The MCP server registers over 80 tools organized by their target service:

Quran

• quranenc_translation_list: Get lists of translations (e.g. English, French, Urdu).
• quranenc_translation_sura: Fetch translation for a complete surah.
• quranenc_translation_aya: Fetch translation for a specific ayah.
• quranenc_aya_audio: Get audio file URL (MP3) for an ayah.
• islamhouse_quran_categories, islamhouse_quran_sura_details, etc.

Hadith

• hadeethenc_languages: Get supported translation languages.
• hadeethenc_categories: Retrieve Hadith categories.
• hadeethenc_hadiths_list: List hadiths inside a category.
• hadeethenc_hadith_details: Get the Arabic text, translation, explanation, and references of a single hadith.

IslamHouse General

• islamhouse_list_items: Query books, audios, videos, and fatwas.
• islamhouse_item_details: Fetch full details and attachments (PDFs/Audios) of an item.
• islamhouse_list_authors: Get authors/scholars details.

Specialized Services

• Al-Montaka: almontaka_content, almontaka_comments, lookup tables (entities, tags, etc.).
• Bayan Al-Islam: bayan_muslim_list, bayan_name_search, bayan_content_translation.
• Risalat Al-Haramain: risala_get_contents, risala_fatwas, risala_hadeeths.

Developer Guide (Local Development)

If you want to clone, modify, or run the server locally:

1. Clone the Repository

git clone https://github.com/2yousefreda/islamic-content-mcp.git
cd islamic-content-mcp

2. Install Dependencies & Build

npm install
npm run build

3. Run Locally (via Stdio)

node dist/bin.js

To 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"]

Donation & Support

You can support the projects and efforts of The Association for Multi-lingual Islamic Content through the following official channels:

• Support Projects (Wakfy)
• Bank Accounts
• Association Store
• Annual Operational Support (الدعم التشغيلي السنوي للجمعية)

License

This project is licensed under the ISC License.