MCP Server for Quran.com API

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

概述

这是一个从 OpenAPI 规范 生成的 Model Context Protocol (MCP) 服务器。

端点

以下 API 端点已作为工具提供，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 镜像：

bash

构建 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%Claudeclaude_desktop_config.json）：

基于 Docker 的生产模式

json
{
"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）

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

开发模式

json
{
"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 替换为实际的 API 密钥（如果 Quran.com API 需要）
• 如果您已经配置了其他 MCP 服务器，请将此配置添加到现有的 mcpServers 对象中
• 更新配置后，重启 Claude Desktop 以使更改生效

环境变量

• API_KEY: 用于身份验证的 API 密钥* PORT: 服务器端口（默认：根据语言不同为8000或3000）
• VERBOSE_MODE: 设置为 true 以启用API请求和响应的详细日志记录（默认：false）

详细模式

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

详细的日志记录包括：

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

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

测试

bash

运行测试

npm test

许可证

本项目采用MIT许可证。