使用说明

项目简介

Quran.com API MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的应用后端，它将 Quran.com 官方 REST API v4 的多个接口封装成一系列工具，以便大型语言模型（LLM）客户端（如 Claude）能够以标准化的方式访问和利用古兰经数据。

主要功能点

章节查询：
- 获取章节列表（支持按语言筛选）。
- 获取指定章节的详细信息（支持按语言）。
- 获取章节信息，如启示地点、次序等（支持按语言）。
经文查询：
- 根据章节号、页码、Juz、Hizb 或 Rub el Hizb 号码获取经文列表。
- 根据经文 Key 精确查询经文。
- 获取随机经文。
Juz 查询：
- 获取所有 Juz 的列表。
搜索功能：
- 在古兰经中搜索特定关键词（支持指定语言）。
翻译资源：
- 获取可用翻译列表（支持按语言筛选）。
- 获取特定翻译的详细信息。
Tafsir 注释资源：
- 获取可用 Tafsir 注释列表（支持按语言筛选）。
- 获取特定 Tafsir 注释的详细信息。
- 获取指定 Tafsir 注释的内容。
音频资源：
- 获取章节朗诵者列表。
- 获取可用的朗诵风格列表。
语言资源：
- 获取所有支持的语言列表。

所有工具返回的数据均为 JSON 格式的文本内容，方便 LLM 理解和使用。

安装步骤

环境准备：

确保已安装 Node.js 22+ 和 Docker（如果使用 Docker 部署）。
克隆 GitHub 仓库 'https://github.com/djalal/quran-mcp-server' 到本地。

git clone https://github.com/djalal/quran-mcp-server
cd quran-mcp-server

安装依赖：
- 在项目根目录下运行 'npm install' 安装项目依赖。
```
npm install
```
构建项目：
- 运行 'npm run build' 构建项目。
```
npm run build
```
Docker 镜像构建（可选）：
- 如果选择 Docker 部署，在项目根目录下运行 'docker build -t quran-mcp-server .' 构建 Docker 镜像。
```
docker build -t quran-mcp-server .
```

服务器配置

要将此 MCP 服务器与 MCP 客户端（例如 Claude Desktop）集成，您需要配置客户端的 MCP 服务器设置。以下是针对不同部署模式的配置示例，您需要将以下 JSON 配置添加到 Claude Desktop 的 'claude_desktop_config.json' 文件中（通常位于 '~/Library/Application Support/Claude/claude_desktop_config.json' (macOS) 或 '%APPDATA%\Claude\claude_desktop_config.json' (Windows)）。

注意： 以下配置均为 JSON 格式，您只需复制粘贴到 'claude_desktop_config.json' 文件的 'mcpServers' 字段中即可。请根据您的实际部署方式选择相应的配置，并替换占位符路径。

1. Docker 生产模式配置

{
  "mcpServers": {
    "quran-api": {  // 服务器名称，可以自定义
      "command": "docker", // 启动命令为 docker
      "args": ["run", "-i", "--rm", "--init", "-e", "API_KEY=your_api_key_if_needed", "-e", "VERBOSE_MODE=true", "quran-mcp-server"], // Docker 运行参数
      "disabled": false, // 禁用状态，false 为启用
      "autoApprove": [] // 自动批准的工具列表，默认为空
    }
  }
}

参数说明：

'"command": "docker"'：指定使用 Docker 命令运行服务器。
'"args": ["run", "-i", "--rm", "--init", "-e", "API_KEY=your_api_key_if_needed", "-e", "VERBOSE_MODE=true", "quran-mcp-server"]'：Docker 运行参数，包括：
- 'run'：运行容器。
- '-i'：保持标准输入打开。
- '--rm'：容器退出后自动删除。
- '--init'：在容器内运行初始化进程。
- '-e "API_KEY=your_api_key_if_needed"'：设置 API_KEY 环境变量（如果 Quran.com API 需要 API 密钥，请替换 'your_api_key_if_needed' 为您的实际 API 密钥，如果不需要则保持默认）。
- '-e "VERBOSE_MODE=true"'：启用详细日志模式。
- '"quran-mcp-server"'：Docker 镜像名称。

2. Node.js 生产模式配置

{
  "mcpServers": {
    "quran-api": {  // 服务器名称，可以自定义
      "command": "node", // 启动命令为 node
      "args": ["/path/to/quran-mcp-server/dist/src/server.js"], // Node.js 启动参数，指向编译后的服务器 JavaScript 文件
      "env": {
        "API_KEY": "your_api_key_if_needed", // API 密钥环境变量（如果需要，请替换）
        "VERBOSE_MODE": "true" // 启用详细日志模式
      },
      "disabled": false, // 禁用状态，false 为启用
      "autoApprove": [] // 自动批准的工具列表，默认为空
    }
  }
}

参数说明：

'"command": "node"'：指定使用 Node.js 命令运行服务器。
'"args": ["/path/to/quran-mcp-server/dist/src/server.js"]'：Node.js 启动参数，请将 '/path/to/quran-mcp-server' 替换为实际的项目 'quran-mcp-server' 仓库在您系统中的路径。 例如：'["/Users/yourusername/Documents/quran-mcp-server/dist/src/server.js"]'。
'"env": { ... }'：设置环境变量：
- '"API_KEY": "your_api_key_if_needed"'：设置 API_KEY 环境变量（如果 Quran.com API 需要 API 密钥，请替换 'your_api_key_if_needed' 为您的实际 API 密钥，如果不需要则保持默认）。
- '"VERBOSE_MODE": "true"'：启用详细日志模式。

3. 开发模式配置

{
  "mcpServers": {
    "quran-api": {  // 服务器名称，可以自定义
      "command": "npx", // 启动命令为 npx
      "args": ["ts-node", "/path/to/quran-mcp-server/src/server.ts"], // npx 启动参数，使用 ts-node 直接运行 TypeScript 服务器代码
      "env": {
        "API_KEY": "your_api_key_if_needed", // API 密钥环境变量（如果需要，请替换）
        "VERBOSE_MODE": "true" // 启用详细日志模式
      },
      "disabled": false, // 禁用状态，false 为启用
      "autoApprove": [] // 自动批准的工具列表，默认为空
    }
  }
}

参数说明：

'"command": "npx"'：指定使用 'npx' 命令运行服务器。
'"args": ["ts-node", "/path/to/quran-mcp-server/src/server.ts"]'：'npx' 启动参数，使用 'ts-node' 直接运行 TypeScript 服务器代码，请将 '/path/to/quran-mcp-server' 替换为实际的项目 'quran-mcp-server' 仓库在您系统中的路径。 例如：'["/Users/yourusername/Documents/quran-mcp-server/src/server.ts"]'。
'"env": { ... }'：设置环境变量，与生产模式配置相同。

重要提示：

路径替换： 请务必将配置中的 '/path/to/quran-mcp-server' 替换为您本地仓库的实际路径。
API 密钥： 如果 Quran.com API 需要 API 密钥，请替换 'your_api_key_if_needed' 为您的实际 API 密钥。您可以先尝试不配置 API 密钥运行，如果遇到权限问题再配置。
重启 Claude Desktop： 修改 'claude_desktop_config.json' 文件后，需要重启 Claude Desktop 才能使配置生效。

基本使用方法

启动 MCP 服务器：根据您选择的部署模式（Docker 或 Node.js），按照 README.md 文件中的 "Setup" 章节指引启动 MCP 服务器。
配置 Claude Desktop：将上述相应的服务器配置 JSON 代码添加到 Claude Desktop 的 'claude_desktop_config.json' 文件中，并确保配置正确。
在 Claude 中使用：在 Claude 中，您可以指示 Claude 使用 'quran-api' 服务器提供的工具来查询古兰经数据。例如，您可以这样提问：
- "列出古兰经的所有章节 (使用 list-chapters 工具)"
- "获取第一章 Al-Fatihah 的信息 (使用 GET-chapter 工具，章节 ID 为 1)"
- "搜索关于 'mercy' 的经文 (使用 search 工具，关键词为 mercy)"
Claude 将会调用 'quran-api' 服务器提供的工具，并将返回的结果用于生成回复。

详细日志 (Verbose Mode):

如果配置中设置了 'VERBOSE_MODE: "true"'，服务器会将详细的 API 请求和响应日志输出到控制台，这有助于调试和监控服务器运行情况。

关键词

使用说明

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息