Tafsir Mcp

🕌 Tafsir MCP

خادم MCP العلمي للقرآن الكريم — برعاية مركز تفسير للدراسات القرآنية

[](https://pypi.org/project/tafsir-mcp/) [](LICENSE) [](LICENSE-DATA) [](https://modelcontextprotocol.io) [](https://tafsir.net)

[العربية](#arabic) · [English](#english)

---

🌙 نبذة

خادم Model Context Protocol (MCP) يوفّر وصولاً علمياً موثّقاً للقرآن الكريم لأي مساعد ذكي يدعم MCP (Claude Code، Claude Desktop، VS Code، وغيرها).

كل البيانات مراجعة ومعتمدة من مركز تفسير للدراسات القرآنية.

---

✨ المميزات

• 📖 6,236 آية كاملة بالرسم العثماني
• 📚 5 تفاسير كلاسيكية: الطبري · ابن كثير · البغوي · السعدي · الميسر
• 🌍 المختصر في التفسير بـ3 لغات (عربي، إنجليزي، بنغالي)
• 🔤 77,432 كلمة بتحليل لغوي شامل (إعراب، صرف، جذر، رسم)
• 🔍 1,891 جذر قابل للبحث والإحصاء
• ⚡ بحث FTS5 سريع مع تطبيع عربي كامل (بدون تشكيل)
• 🎵 اختلاف القراءات لكل آية وكلمة
• 📜 أسباب النزول بالإسناد الكامل (201 آية)
• 📊 إحصاءات تفصيلية لكل سورة وصفحة مصحف
• 🛡️ حماية صارمة من الهلوسة (Pydantic v2 validation)
• 📴 يعمل دون إنترنت بعد التثبيت

---

🚀 التثبيت السريع

لمستخدمي Claude Code:

claude mcp add tafsir --scope user -- uvx tafsir-mcp

للتثبيت اليدوي:

pip install tafsir-mcp
# أو
uvx tafsir-mcp

عند أول تشغيل، سيُحمَّل ملف البيانات (~214 MB) من Hugging Face تلقائياً ويُخزَّن في ~/.cache/tafsir-mcp/.

للمطوّرين (من المصدر):

git clone https://github.com/tafsircenter/tafsir-mcp
cd tafsir-mcp
cp /path/to/quran.db data/quran.db   # أو: export TAFSIR_DB_PATH=/path/to/quran.db
uv sync
uv run tafsir-mcp

---

🌐 الاستضافة والنشر

الإنتاج مُستضاف على Fly.io (region bom/Mumbai) خلف النطاق الرسمي https://mcp.tafsir.net/mcp (MCP-over-HTTP، فحص صحة على /health). أي عميل يدعم HTTP transport يتّصل مباشرةً دون تثبيت محلي.

نسخة Hugging Face Space السابقة أصبحت أرشيفًا خاصًّا (Private، غير حيّة) — انظر docs/ADR/0001-fly-over-hf-space.md.

---

🔧 ربط Claude Desktop

أضف إلى ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tafsir": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/YOUR_USERNAME/projects/quranic-scholar-mcp",
        "run",
        "tafsir-mcp"
      ]
    }
  }
}

---

🧰 الأدوات المتاحة (13 أداة)

| الفئة | الأداة | الوصف | |---|---|---| | الآية | fetch_ayah | نص آية بالرسم العثماني، مع تجويد/إعراب اختياري | | | fetch_tafsir | تفسير من 8 مصادر (تفاسير متعددة بطلب واحد) | | | fetch_nuzool_reason | سبب النزول بالإسناد الكامل | | السورة | fetch_surah_info | معلومات شاملة: أهداف، فضائل، نزول | | | get_surah_statistics | إحصاءات: كلمات، حروف، أطول كلمة... | | الكلمة | analyze_word | إعراب، صرف، معنى، جذر، قراءات | | | find_root_occurrences | كل مواضع جذر في القرآن | | | get_root_stats | إحصاءات جذر: سور، آيات، أوزان | | البحث | search_quran_text | بحث FTS5 بدون تشكيل | | | search_in_tafsir | بحث LIKE في متن تفسير محدد | | القراءات | get_qeraat_variants | اختلاف القراءات لآية أو كلمة | | عام | get_quran_overview | إحصاءات شاملة للقرآن | | | get_page_fawaed | فوائد صفحة من المصحف |

---

📋 الموارد والقوالب

الموارد (Resources)

| المورد | الوصف | |--------|-------| | quran://surahs | فهرس 114 سورة (JSON) | | quran://tafsirs | فهرس 8 مصادر تفسيرية مع الإسناد (JSON) | | quran://schema | توثيق مخطط قاعدة البيانات (Markdown) |

قوالب الدراسة (Prompts)

| القالب | الوصف | |--------|-------| | study_ayah(surah, ayah) | دراسة شاملة: نص + تفسير + إعراب + كلمات | | compare_tafsirs(surah, ayah) | مقارنة التفاسير الخمسة | | root_study(root) | دراسة جذر: إحصاء + مواضع + سياقات | | surah_overview(surah) | نظرة شاملة على سورة | | tajweed_lesson(surah, ayah) | درس تجويد: أحكام + قراءات |

---

📚 مصادر التفسير

| المعرّف | الكتاب | المؤلف | الوفاة | |---------|--------|--------|--------| | tabary | جامع البيان | أبو جعفر الطبري | 310هـ | | katheer | تفسير ابن كثير | أبو الفداء إسماعيل بن كثير | 774هـ | | baghawy | معالم التنزيل | الحسين بن مسعود البغوي | 510هـ | | saadi | تيسير الكريم الرحمن | عبد الرحمن بن ناصر السعدي | 1376هـ | | moyassar | التفسير الميسر | مجمع الملك فهد | — | | mukhtasar_ar | المختصر (عربي) | مجمع الملك فهد | — | | mukhtasar_en | Concise Commentary (English) | King Fahd Complex | — | | mukhtasar_bn | সংক্ষিপ্ত তাফসীর (Bengali) | King Fahd Complex | — |

---

🗂️ بنية المشروع

src/tafsir/
├── server.py          # FastMCP entry point
├── db.py              # SQLite read-only connection
├── data_loader.py     # DB path resolver + auto-download
├── models.py          # Pydantic models + attributions
├── normalize.py       # Arabic text normalization
├── tools/             # 13 MCP tools
├── resources/         # 3 MCP resources
└── prompts/           # 5 study prompt templates

---

🧪 الاختبارات

uv run pytest tests/ -v
# 35 tests — all pass

---

🔒 الأمان

• قاعدة البيانات تُفتح للقراءة فقط: mode=ro + PRAGMA query_only=ON
• جميع مدخلات المستخدم عبر ? placeholders — لا SQL injection
• الأدوات لا تصل للشبكة (openWorldHint=False)

---

📜 الترخيص

• الكود: [MIT License](LICENSE) — Ahmed Eid, Tafsir Center for Quranic Studies
• قاعدة البيانات: [CC BY 4.0](LICENSE-DATA) — يجب نسبة المصدر لمركز تفسير

---

🏛️ الجهة الراعية

هذا المشروع رعاية ودعم مركز تفسير للدراسات القرآنية. البيانات القرآنية مراجعة وموثّقة من قِبل الباحثين العلميين في المركز.

📧 cloud@tafsir.net

---

🌙 About

A Model Context Protocol (MCP) server providing scholarly, certified access to the Holy Quran for any MCP-compatible AI assistant (Claude Code, Claude Desktop, VS Code, etc.).

All data is reviewed and certified by Tafsir Center for Quranic Studies.

✨ Features

• 📖 6,236 ayahs in Uthmani script
• 📚 5 classical Arabic tafsirs: Tabari · Ibn Kathir · Baghawi · Saadi · Muyassar
• 🌍 Trilingual Mukhtasar (Arabic, English, Bengali)
• 🔤 77,432 words with full linguistic analysis (i'rab, sarf, root, rasm)
• 🔍 1,891 roots searchable with statistics
• ⚡ FTS5 search with full Arabic normalization (diacritic-free)
• 🎵 Qira'at variants per ayah and word
• 📜 Asbab al-nuzool with full isnad (201 ayahs)
• 📊 Detailed statistics per surah and mushaf page
• 🛡️ Hallucination protection (strict Pydantic v2 validation)
• 📴 Fully offline after installation

🚀 Quick Install

# Claude Code
claude mcp add tafsir --scope user -- uvx tafsir-mcp

# pip / uvx
pip install tafsir-mcp
uvx tafsir-mcp

On first run, the database (~214 MB) is downloaded automatically from Hugging Face and cached at ~/.cache/tafsir-mcp/.

🧰 Available Tools (13)

| Category | Tool | Description | |---|---|---| | Ayah | fetch_ayah | Ayah text with optional tajweed/i'rab | | | fetch_tafsir | Tafsir from up to 8 sources in one call | | | fetch_nuzool_reason | Asbab al-nuzool with full isnad | | Surah | fetch_surah_info | Full surah info: goals, virtues, revelation | | | get_surah_statistics | Word count, char count, longest word... | | Word | analyze_word | I'rab, sarf, meaning, root, qira'at | | | find_root_occurrences | All occurrences of a root in the Quran | | | get_root_stats | Root stats: surahs, ayahs, distinct forms | | Search | search_quran_text | FTS5 diacritic-free search | | | search_in_tafsir | LIKE search in a tafsir text | | Qira'at | get_qeraat_variants | Reading variants for ayah or word | | General | get_quran_overview | Quran-wide statistics | | | get_page_fawaed | Fawaed for a mushaf page |

📜 License

• Code: [MIT](LICENSE) — Ahmed Eid, Tafsir Center for Quranic Studies
• Quranic Data: [CC BY 4.0](LICENSE-DATA) — attribution to "Tafsir Center for Quranic Studies" required

🏛️ Sponsor

Sponsored by Tafsir Center for Quranic Studies.

📧 cloud@tafsir.net · GitHub Issues

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tafsircenter
• Source: tafsircenter/tafsir-mcp
• License: MIT
• Homepage: https://tafsir.net

Install and usage instructions live in the source repository linked above.