quran-mcp-server

Quran.com API 的 MCP 服务器

MCP 服务器通过官方REST API v4与 Quran.com 语料库进行交互。

概述

这是根据OpenAPI 规范生成的模型上下文协议 (MCP) 服务器。

端点

API 中的以下端点已作为工具提供，LLM 可以通过兼容的客户端使用。

章节

• GET /chapters - 列出章节
• GET /chapters/{id} - 获取章节
• GET /chapters/{chapter_id}/info - 获取章节信息

诗句

• GET /verses/by_chapter/{chapter_number} - 按章节/Surah 编号获取诗句
• GET /verses/by_page/{page_number} - 获取特定 Madani Mushaf 页面的所有诗句
• GET /verses/by_juz/{juz_number} - 根据 Juz 编号获取诗句
• GET /verses/by_hizb/{hizb_number} - 根据 Hizb 编号获取诗句
• GET /verses/by_rub/{rub_el_hizb_number} - 根据 Rub el Hizb 编号获取诗句
• GET /verses/by_key/{verse_key} - 按键获取诗句
• GET /verses/random - 获取随机诗句

朱兹

• GET /juzs - 获取所有 juzs 的列表

搜索

• GET /search - 在《古兰经》中搜索特定术语

翻译

• GET /resources/translations - 获取可用翻译列表
• GET /resources/translations/{translation_id}/info - 获取特定翻译的信息

塔夫西尔

• GET /resources/tafsirs - 获取可用 tafsirs 列表
• GET /resources/tafsirs/{tafsir_id}/info - 获取特定 tafsir 的信息
• GET /quran/tafsirs/{tafsir_id} - 获取单个 tafsir

声音的

• GET /resources/chapter_reciters - 章节朗诵者列表
• GET /resources/recitation_styles - 获取可用的朗诵风格

语言

• GET /resources/languages - 获取所有语言

设置

要求

• Node.js 22+
• Docker

构建 Docker 镜像

在使用基于Docker的生产模式之前，需要构建Docker镜像：

Claude 桌面集成

要将此 MCP 服务器与 Claude Desktop 一起使用，请将以下配置添加到您的claude_desktop_config.json文件中（在 macOS 上通常位于~/Library/Application Support/Claude/claude_desktop_config.json ，在 Windows 上通常位于%APPDATA%\Claude\claude_desktop_config.json ）：

基于Docker的生产模式

生产模式（Node.js）

开发模式

重要提示：

• 将/path/to/quran-mcp-server替换为系统上此存储库的实际路径
• 您需要先使用npm run build或docker build -t quran-mcp-server .如果使用生产模式配置
• 如果 Quran.com API 需要，请将your_api_key_if_needed替换为实际的 API 密钥
• 如果您已经配置了其他 MCP 服务器，请将此配置添加到现有的mcpServers对象
• 更新配置后，重新启动 Claude Desktop 以使更改生效

环境变量

• API_KEY ：用于身份验证的 API 密钥
• PORT ：服务器端口（默认值：8000 或 3000，取决于语言）
• VERBOSE_MODE ：设置为“true”以启用 API 请求和响应的详细日志记录（默认值：false）

详细模式

当VERBOSE_MODE设置为“true”时，服务器会将有关 API 请求和响应的详细信息记录到控制台。这对于调试和监控 API 交互非常有用。

详细日志记录包括：

• 请求：记录每个传入请求的工具名称和参数
• 响应：记录每个响应的工具名称和结果数据
• 错误：记录详细的错误信息，包括错误名称、消息和堆栈跟踪（如果可用）

每个日志条目都带有时间戳，并以日志类型（REQUEST、RESPONSE 或 ERROR）为前缀，以便于识别。

测试

执照

该项目已获得 MIT 许可。