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镜像：

# Build the Docker image
docker build -t quran-mcp-server .

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的生产模式

{
  "mcpServers": {
    "quran-api": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "-e", "API_KEY=your_api_key_if_needed", "-e", "VERBOSE_MODE=true", "quran-mcp-server"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

生产模式（Node.js）

{
  "mcpServers": {
    "quran-api": {
      "command": "node",
      "args": ["/path/to/quran-mcp-server/dist/src/server.js"],
      "env": {
        "API_KEY": "your_api_key_if_needed",
        "VERBOSE_MODE": "true" // Set to "true" to enable verbose logging
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

开发模式

{
  "mcpServers": {
    "quran-api": {
      "command": "npx",
      "args": ["ts-node", "/path/to/quran-mcp-server/src/server.ts"],
      "env": {
        "API_KEY": "your_api_key_if_needed",
        "VERBOSE_MODE": "true" // Set to "true" to enable verbose logging
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

重要提示：

将/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）为前缀，以便于识别。

测试

# Run tests
npm test

执照

该项目已获得 MIT 许可。

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

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