Quran MCP Server

Quran.com API的MCP服务器

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

概述

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

端点

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

章节

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

诗句

• GET/vons/by_chapter/{chapter_number}-按章节/章节编号获取经文
• GET/vons/by_page/{page_number}-获取特定Madani Mushaf页面的所有诗句
• GET /verses/by_juz/{juz_number} - 根据 Juz 号码获取诗句
• GET/vons/by_hizb/{hizb_number}-按真主党数字获取经文
• GET/vons/by_rub/{rub_el_hizb_number}-通过rub-el-hizb数字获取诗句
• GET/vers/by_key/{verse_key}-按键获取诗句
• GET/verses/random-获取一个随机的诗句

朱兹

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

搜索

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

翻译

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

解释

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

音频

• GET/resources/chapter_引用者-章节引用者列表
• 获取/资源/复习_样式-获取可用的复习样式

语言

• GET/资源/语言-获取所有语言

设置

需求

• Node.js 22+
• 码头工人

构建Docker镜像

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

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

Claude桌面集成

要将此MCP服务器与Claude Desktop一起使用，请将以下配置添加到您的 claude_desktop_config.json 文件（通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS或 %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

基于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 . 如果使用生产模式配置
• 替换 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）作为前缀，以便于识别。

测试

# Run tests
npm test

许可证

该项目根据MIT许可证获得许可。