Quran Mcp Server

🚀 Quran.com API 的 MCP 服务器

本 MCP 服务器可借助官方的 REST API v4 与 Quran.com 的文本实现交互。

🚀 快速开始

此 MCP 服务器由 OpenAPI 规范 (v4.json) 生成。若要运行测试，可执行以下命令：

# 运行测试
npm test

✨ 主要特性

该服务器提供了丰富的 API 端点，LLM 可通过兼容客户端使用，涵盖了章节、经文、Juzs、搜索、翻译等多方面的查询功能。

📦 安装指南

文档未提及具体安装步骤，暂无法提供。

💻 使用示例

基础用法

以下是部分 API 端点的使用示例：

• 获取章节列表：

GET /chapters

• 获取一条随机经文：

GET /verses/random

高级用法

# 在古兰经中搜索特定术语
GET /search?term=your_search_term

📚 详细文档

端点详情

章节

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

经文

• GET /verses/by_chapter/{chapter_number}：按章节/苏拉编号获取经文
• 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：获取一条随机经文

Juzs

• GET /juzs：获取所有 Juz 的列表

搜索

• GET /search：在古兰经中搜索特定术语

翻译

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

环境变量

详细日志模式

当 VERBOSE_MODE 设置为 'true' 时，服务器会在控制台中输出详细的 API 请求和响应日志，这对于调试和监控 API 交互非常有用。详细日志包括请求、响应和错误信息，每条日志都带有时间戳，并且前面有标识符（如 REQUEST、RESPONSE 或 ERROR），以便于识别。

环境配置示例

使用 bash：

export API_KEY="your_api_key_here"
export PORT=8000
export VERBOSE_MODE=true

使用 PowerShell（Windows）：

$env:API_KEY = "your_api_key_here"
$env:PORT = 8000
$env:VERBOSE_MODE = "true"

在 Claude Desktop 中配置

将以下内容添加到 claudius.json 配置文件中：

{
"mcpServers": {
"quranComMCP": {
"type": "custom",
"executablePath": "/path/to/node/bin/npm",  // 根据实际 Node.js 安装路径填写
"scriptName": "start",
"args": [
"--port",
"8000",
"--api-key",
"your_api_key_here"
],
"environmentVariables": {
"VERBOSE_MODE": "true"  // 启用详细日志模式
}
}
}
}

然后根据实际路径调整 executablePath，替换 your_api_key_here 为实际的 API 密钥，保存文件并重启 Claude Desktop 以使配置生效。

完整的日志示例

当 VERBOSE_MODE 启用时，控制台输出可能如下：

[2023-10-01 12:34:56] REQUEST - GET /verses/random
[2023-10-01 12:34:57] RESPONSE - {
"chapter": {
"number": 1,
"name": "Al-Fatiha",
"translation": "The Opening"
},
"verse": {
"number": 1,
"text": "In the name of Allah, Most Gracious, Most Merciful..."
}
}
[2023-10-01 12:35:01] ERROR - 获取经文时发生错误：网络连接中断

🔧 技术细节

文档未提及具体技术实现细节，暂无法提供。

📄 许可证

此项目遵循 MIT 许可证。