MCP Server for Quran.com API

Quran.com API 用 MCP サーバー

公式の REST API v4 を通じて、Quran.com のコーパスを操作する MCP サーバーです。

概要

これは、OpenAPI 仕様から生成された Model Context Protocol（MCP）サーバーです。

エンドポイント

以下の API エンドポイントをツールとして利用でき、LLM は互換性のあるクライアントを通じて使用できます。

章

• 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 イメージをビルドする必要があります。

# Build the Docker image
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" // 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 . でプロジェクトをビルドする必要があります
• Quran.com API が必要とする場合は、your_api_key_if_needed を実際の API キーに置き換えてください
• すでにほかの MCP サーバーを設定している場合は、この設定を既存の mcpServers オブジェクトに追加してください
• 設定を更新した後、変更を反映するために Claude Desktop を再起動してください

環境変数

• API_KEY：認証用 API キー
• PORT：サーバーのポート（デフォルト：言語に応じて 8000 または 3000）
• VERBOSE_MODE：API リクエストとレスポンスの詳細なログを有効にするには 'true' に設定します（デフォルト：false）

詳細ログモード

VERBOSE_MODE を 'true' に設定すると、サーバーは API リクエストとレスポンスの詳細情報をコンソールに記録します。これは、API のやり取りのデバッグや監視に役立ちます。

詳細ログには以下が含まれます。

• リクエスト：受信した各リクエストのツール名と引数を記録します
• レスポンス：各レスポンスのツール名と結果データを記録します
• エラー：エラー名、メッセージ、利用可能な場合はスタックトレースなど、詳細なエラー情報を記録します

各ログエントリにはタイムスタンプが付与され、識別しやすいようにログの種類（REQUEST、RESPONSE、ERROR）が先頭に付加されます。

テスト

# Run tests
npm test

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。