MCP Server for Quran.com API

Quran.com API 的 MCP 服务

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

概览

这是一个根据 OpenAPI 规范生成的 Model Context Protocol（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 - 获取随机经文

Juz

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

搜索

• GET /search - 搜索 Quran 中的指定词语

译文

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

Tafsir

• GET /resources/tafsirs - 获取可用 Tafsir 列表
• 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 Desktop 集成

要将此 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 要求提供 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 License 许可。