Quran.com API 的 MCP 服务器

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

概述

这是一个从 OpenAPI 规范 生成的模型上下文协议 (MCP) 服务器。

接口

以下 API 接口已作为工具提供，LLM 可以通过兼容的客户端使用。

Chapters (章节)

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

Verses (经文)

• GET /verses/by_chapter/{chapter_number} - 按章节/古兰经编号获取经文
• GET /verses/by_page/{page_number} - 获取特定麦地那 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 - 获取所有节的列表

Search (搜索)

• GET /search - 搜索古兰经中的特定术语

Translations (翻译)

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

Tafsirs (泰夫西尔)

• GET /resources/tafsirs - 获取可用泰夫西尔的列表
• GET /resources/tafsirs/{tafsir_id}/info - 获取特定泰夫西尔的信息
• GET /quran/tafsirs/{tafsir_id} - 获取单个泰夫西尔

Audio (音频)

• GET /resources/chapter_reciters - 章节朗诵者列表
• GET /resources/recitation_styles - 获取可用的朗诵风格

Languages (语言)

• GET /resources/languages - 获取所有语言

设置

Requirements (要求)

• Node.js 22+
• Docker

Building the Docker Image (构建 Docker 镜像)

在使用基于 Docker 的生产模式之前，您需要构建 Docker 镜像：

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

Claude Desktop Integration (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-based Production Mode (基于 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": []
    }
  }
}

Production Mode (Node.js) (生产模式 (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": []
    }
  }
}

Development Mode (开发模式)

{
  "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": []
    }
  }
}

Important Notes (重要提示):

• Replace /path/to/quran-mcp-server with the actual path to this repository on your system (将 /path/to/quran-mcp-server 替换为您系统上此存储库的实际路径)
• You'll need to build the project first with npm run build or docker build -t quran-mcp-server . if using the production mode configuration (如果使用生产模式配置，您需要首先使用 npm run build 或 docker build -t quran-mcp-server . 构建项目)
• Replace your_api_key_if_needed with an actual API key if required by the Quran.com API (如果 Quran.com API 需要，请将 your_api_key_if_needed 替换为实际的 API 密钥)
• If you already have other MCP servers configured, add this configuration to the existing mcpServers object (如果您已经配置了其他 MCP 服务器，请将此配置添加到现有的 mcpServers 对象)
• After updating the configuration, restart Claude Desktop for the changes to take effect (更新配置后，重新启动 Claude Desktop 以使更改生效)

Environment Variables (环境变量)

• API_KEY: API key for authentication (用于身份验证的 API 密钥)
• PORT: Server port (default: 8000 or 3000 depending on language) (服务器端口（默认值：8000 或 3000，具体取决于语言）)
• VERBOSE_MODE: Set to 'true' to enable verbose logging of API requests and responses (default: false) (设置为“true”以启用 API 请求和响应的详细日志记录（默认值：false）)

Verbose Mode (详细模式)

When VERBOSE_MODE is set to 'true', the server will log detailed information about API requests and responses to the console. This is useful for debugging and monitoring API interactions. (当 VERBOSE_MODE 设置为“true”时，服务器会将有关 API 请求和响应的详细信息记录到控制台。这对于调试和监视 API 交互非常有用。)

The verbose logging includes: (详细日志记录包括：)

• Requests: Logs the tool name and arguments for each incoming request (请求：记录每个传入请求的工具名称和参数)
• Responses: Logs the tool name and result data for each response (响应：记录每个响应的工具名称和结果数据)
• Errors: Logs detailed error information including error name, message, and stack trace when available (错误：记录详细的错误信息，包括错误名称、消息和堆栈跟踪（如果可用）)

Each log entry is timestamped and prefixed with the log type (REQUEST, RESPONSE, or ERROR) for easy identification. (每个日志条目都带有时间戳，并以日志类型（REQUEST、RESPONSE 或 ERROR）作为前缀，以便于识别。)

Testing (测试)

# Run tests
npm test

License (许可证)

This project is licensed under the MIT License. (本项目根据 MIT 许可证获得许可。)