JinDaGe - quran-mcp-server MCP Details

article

README

🚀 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：获取特定翻译的信息

环境变量

| 属性 | 详情 | |------|------| | API_KEY | 用于身份验证的 API 密钥 | | PORT | 服务器端口（默认：8000 或 3000，具体取决于语言） | | VERBOSE_MODE | 设置为 'true' 可以启用详细日志记录模式（默认：false） |

详细日志模式

当 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 许可证。

quran-mcp-server