MCP Server for Quran.com API

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

概述

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

端点

以下端点已作为工具提供，LLMs可以通过兼容客户端使用这些工具。

章节

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

节

• GET /verses/by_chapter/{chapter_number} - 根据章节/苏拉编号获取节
• GET /verses/by_page/{page_number} - 获取特定麦地那穆沙法页面的所有节
• GET /verses/by_juz/{juz_number} - 根据朱兹编号获取节
• GET /verses/by_hizb/{hizb_number} - 根据希卜编号获取节
• GET /verses/by_rub/{rub_el_hizb_number} - 根据鲁布尔希卜编号获取节
• GET /verses/by_key/{verse_key} - 根据键获取节
• GET /verses/random - 随机获取一节

朱兹

• GET /juzs - 获取所有朱兹列表

搜索

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

翻译

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

注释

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

音频

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

语言

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

设置

要求

• Node.js 22+
• Docker

构建Docker镜像

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

# 构建Docker镜像
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" // 设置为"true"以启用详细日志记录
      },
      "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" // 设置为"true"以启用详细日志记录
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

重要说明：

• 将/path/to/quran-mcp-server替换为您系统上此存储库的实际路径
• 如果使用生产模式配置，您需要先用npm run build或docker build -t quran-mcp-server .构建项目
• 将your_api_key_if_needed替换为Quran.com API所需的实际API密钥
• 如果已经配置了其他MCP服务器，请将此配置添加到现有的mcpServers对象中
• 更新配置后，请重启Claude Desktop以使更改生效

环境变量

• API_KEY: 认证使用的API密钥
• PORT: 服务器端口（默认：8000或3000，取决于语言）
• VERBOSE_MODE: 设置为'true'以启用API请求和响应的详细日志记录（默认：false）

详细模式

当VERBOSE_MODE设置为'true'时，服务器将在控制台中记录关于API请求和响应的详细信息。这对于调试和监控API交互非常有用。

详细日志包括：

• 请求：记录每个传入请求的工具名称和参数
• 响应：记录每个响应的工具名称和结果数据
• 错误：记录详细的错误信息，包括错误名称、消息和堆栈跟踪（如果可用）

每个日志条目都带有时间戳，并以前缀（REQUEST、RESPONSE或ERROR）标识以便于识别。

测试

# 运行测试
npm test

许可证

本项目根据MIT许可证发布。