moodle-mcp-server-aql

moodle-mcp-server — AI を活用した LMS 分析

Moodle インスタンスについて何でも質問できます。数秒で構造化された回答が得られます。

moodle-mcp-server は、AI エージェントを Moodle の Web Services API に直接接続する、オープンソースの MCP（Model Context Protocol）サーバーです。Agentic Query Layer (AQL) パターンの最初のリファレンス実装です。これは、LLM が構造化データに対して安全で、権限を考慮した読み取り専用アクセスを行えるようにするソフトウェア設計パターンです。

レポートビルダーの使い方を学んだり、SQL を記述したり、CSV をエクスポートしたりする代わりに、自然な言葉で質問できます。AI エージェントが LMS に問い合わせ、構造化データを返します。

AQL パターン： https://csmediapro.com/notes/agentic-query-layer プロジェクトホーム： https://csmediapro.com/products/moodle-mcp-server npm パッケージ： https://www.npmjs.com/package/moodle-mcp-server-aql MCP レジストリ： io.github.csmediapro/moodle-mcp-server-aql

---

機能

• コアクエリツール — コースカタログ、ユーザー登録、課題、カテゴリーナビゲーション、サイトメタデータ、ユーザー検索、キャッシュ管理
• プレミアムレポートプラグイン — コース完了レポートや最近のアクティビティなどのオプションツールを、プラグインランタイムを通じて追加できます
• LLM に依存しません — Claude、GPT、Gemini、Ollama、その他の MCP 対応 AI クライアントで動作します
• LMS の変更は不要 — Moodle の既存の Web Services API を使用し、プラグインのインストールは不要です
• コンプライアンスに対応したデータ処理 — プライバシーを設計段階から考慮した、安全で効率的なデータ処理を実現します
• 読み取り専用 — Moodle のデータを変更することはなく、本番環境でも安全に使用できます
• プラグインで拡張可能 — 新しいツールモジュールをディレクトリに配置すると、ツールやオプションのエージェントルーティングヒントが実行時に自動登録されます

---

クイックスタート

前提条件

• Node.js 20+
• Web Services が有効な Moodle インスタンス
• Moodle API トークン（サイト管理 → プラグイン → Web services → トークンを管理）

MCP クライアントで使用する

ほとんどのユーザーは、Claude Desktop などの MCP クライアントを通じてサーバーを起動します。

{
  "mcpServers": {
    "moodle-mcp-server-aql": {
      "command": "npx",
      "args": ["-y", "moodle-mcp-server-aql"],
      "env": {
        "MOODLE_URL": "https://your-moodle-instance.example",
        "MOODLE_TOKEN": "your-moodle-web-services-token"
      }
    }
  }
}

ソースからセットアップする

# Clone the repo
git clone https://github.com/csmediapro/moodle-mcp-server
cd moodle-mcp-server

# Install dependencies
npm install

# Configure
cp packages/server/.env.example packages/server/.env
# Edit .env: add your MOODLE_URL and MOODLE_TOKEN

# Run (stdio mode)
npm run server:build
node packages/server/dist/index.js

ユーザーフィールドのスキーマ

ユーザーフィールドの表示設定は Moodle インスタンスごとに生成され、ローカルの packages/server/data/user-field-schema.json に保存されます。このファイルにはサイト固有のカスタムプロフィールフィールドが含まれる場合があるため、意図的に git の対象外にしています。

Moodle サイトに接続した後、refresh_user_field_schema ツールを一度実行し、利用可能な標準ユーザーフィールドとカスタムユーザーフィールドを検出してください。最小限のサンプル形式は packages/server/data/user-field-schema.example.json に含まれています。

個別にインストールしたプラグインは、このスキーマを使用してカスタムプロフィールフィールドを school などの安定したキーにフラット化できます。たとえば、プレミアムの user-directory プラグインは、このスキーマを使用して OSS コアの外部で、全ユーザーのディレクトリフィールドをキャッシュして要約します。

設定の ID

コアには、異なるサーバー ID フィールドが 2 つあります。

• server.id — mcp_8f3k2q9x などの、安定したマシン ID
• server.name — ユーザー向けの表示名

server.id が指定されていない場合、コアは ID を一度だけ生成し、起動処理を続ける前に解決済みの設定ファイルに保存します。

環境変数による上書き：

• MOODLE_MCP_CONFIG または MOODLE_MCP_SERVER_CONFIG — 設定ファイルのパスを指定します
• SERVER_ID — server.id を明示的に上書きします
• SERVER_NAME — server.name を明示的に上書きします
• SERVER_VERSION — server.version を明示的に上書きします

server.id が指定されておらず、解決済みの設定ファイルのパスに書き込み権限がない場合、起動は意図的に失敗します。

リファレンスクライアントを使用する

# From the project root
cp packages/client/.env.example packages/client/.env
npm run client:dev
# Open http://localhost:3000

クライアントが Moodle インスタンスを自動検出し、自然な言葉で質問できるチャットインターフェースを表示します。

---

LLM を接続する

moodle-mcp-server の自然言語インターフェースを動作させるには、AI モデルが必要です。モデルはご自身で用意してください。moodle-mcp-server のコアとリファレンスクライアントは、MCP 対応のあらゆるプロバイダーをサポートしています。

オプション 1：ローカルで実行する（速度とプライバシーを重視する場合におすすめ）

ローカルモデルを実行すると、すべてのデータがご自身のハードウェア上に保たれ、ネットワークの外に出ることはありません。最新の量子化モデルは、一般向け GPU でも、CPU のみの環境でも快適に動作します。

パフォーマンス： 単体の RTX 3090 で量子化した 24B モデルを実行すると、初回のクエリ後は約 1.5 秒で応答します。システムの初期化が済めば、ほとんどのクラウド API より高速です。

Ollama を使用する（最も簡単）

# Install Ollama: https://ollama.com
ollama pull gemma3:12b      # Fast, reliable tool use (~200ms TTFT)
ollama pull qwen3:14b       # Strong reasoning, good for complex queries
ollama pull deepseek-r1:14b # Excellent at multi-step chains

その後、リファレンスクライアントの接続先を http://localhost:11434（Ollama のデフォルト）に設定します。

llama.cpp を使用する（最大限の制御）

# Download a GGUF model (example: Devstral 24B Q4)
# Run the llama.cpp server:
llama-server -m devstral-24b-Q4_K_M.gguf --ctx-size 60000 --port 8080

リファレンスクライアントの接続先を http://localhost:8080/v1 に設定します。

おすすめのローカルモデル

モデル	サイズ	最適な用途	ハードウェア
Gemma 3 12B	約 7 GB VRAM	高速なツール呼び出し、単純なクエリ	単体の一般向け GPU
Qwen 3 14B	約 8.5 GB VRAM	複雑な推論、複数ツールの連鎖	単体の一般向け GPU
Devstral 24B Q4	約 14.5 GB VRAM	最高の性能、60K コンテキスト	RTX 3090 / 4090

オプション 2：クラウドプロバイダー

Anthropic（Claude）：

export ANTHROPIC_API_KEY=sk-ant-...

リファレンスクライアントのプロバイダーのドロップダウンから「Anthropic」を選択します。Claude Sonnet は、最も信頼性の高いツール呼び出し動作を提供します。

OpenAI（GPT）：

export OPENAI_API_KEY=sk-...

プロバイダーのドロップダウンから「OpenAI」を選択します。GPT-4o は、構造化されたクエリで優れた性能を発揮します。

Ollama Cloud： ローカルの Ollama と同じ API を使用し、https://ollama.com/v1 でホストされています。ローカル環境のコールドスタートより高速で、大手クラウドプロバイダーよりプライバシーに優れた、バランスのよい選択肢です。

オプション 3：Claude Desktop（MCP に直接接続）

Claude Desktop は、stdio 経由で moodle-mcp-server コアに直接接続するため、リファレンスクライアントは不要です。

Claude Desktop の設定（claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "moodle-mcp-server": {
      "command": "node",
      "args": ["/path/to/moodle-mcp-server/packages/server/dist/index.js"],
      "env": {
        "MOODLE_URL": "https://your-moodle-instance.com",
        "MOODLE_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Desktop を再起動します。サーバーのツールが Claude のツール一覧に表示されるので、直接質問してください。

---

ツール

コアツール（無料、オープンソース — AGPL）

ツール	説明
list_courses	カテゴリを掘り下げて確認できる、全コースの一覧
get_course	任意のコースの詳細表示
list_course_users	登録ユーザーとロール、アクセスデータ（コース名検索と対話形式での選択にも対応）
list_assignments	すべての課題と締め切り
list_categories	正確な親カテゴリ解決に対応した、階層全体の一覧
get_site_info	サイト名、バージョン、コース数などのインスタンス概要
get_user	Moodle ユーザーの詳細表示
list_user_courses	特定ユーザーのコース一覧
search_users	Moodle 標準のユーザー識別フィールドによるユーザー検索
search_courses_by_name	部分一致検索と対話形式での選択による、コース名検索

プレミアムプラグイン（別途提供）

• Advanced Reporting — 成績表、コース間比較、カスタムレポートビルダー
• User Analytics — 進捗状況の追跡、エンゲージメントのスコアリング、リスクフラグ
• User Directory — 標準およびカスタムのプロフィールフィールドを対象とした、キャッシュ済みディレクトリ一覧と構造化フィルタリング
• Compliance Pack — 認定資格の追跡、有効期限のアラート、監査用エクスポート

---

アーキテクチャ

このプロジェクトは、Agentic Query Layer（AQL）パターンのリファレンス実装です。AI エージェントとデータの間に位置するこのレイヤーは、基盤となるデータをモデルに公開することなく、権限を考慮した読み取り専用の自然言語アクセスを提供します。

User (plain English question)
    │
    ▼
AI Agent (Claude / GPT / Gemini / Ollama / local)
    │
    ▼  MCP Protocol
`moodle-mcp-server`  ← AQL connector for Moodle
    ├── Tool Registry (core + plugins)
    ├── Agent Runtime Config (core + plugin rules)
    ├── Optimized Data Layer (secure, efficient data handling)
    └── Moodle Client (REST API calls)
    │
    ▼
Moodle Web Services API

トランスポートモード

• Stdio — dist/index.js — サブプロセスとして実行され、Claude Desktop などのクライアントで使用されます

OSS コアには、意図的に stdio のみが含まれています。ネットワークに接続するラッパー、リモート監視、プレミアムプラグインの接続は、別個の商用ノードエージェントまたはラッパーに属します。

プラグインのドキュメント

• プラグインコントラクト
• プラグインの作成
• Hello Plugin の例

---

ライセンス

AGPL v3 — LICENSEを参照してください。

以下のことができます。

• ✅ moodle-mcp-server のコアを、あらゆる環境で無料で使用する
• ✅ 必要に応じてソースコードを変更する
• ✅ 派生作品を作成して配布する

以下のことはできません。

• ❌ moodle-mcp-server のコアを、クローズドソースの競合する商用製品として再パッケージする
• ❌ 変更内容を共有せずに、ネットワークサービスとして提供する

商標に関するお知らせ

MoodleはMoodle Pty Ltdの商標です。moodle-mcp-server は独立したCSMediaProのプロジェクトであり、Moodle Pty LtdまたはMoodleプロジェクトと提携、承認、後援、あるいは公式に関係しているものではありません。この名称は、Moodle LMSとの互換性を説明する目的で使用されています。

---

CSMediaProによる開発

moodle-mcp-server は、AI統合、システムエンジニアリング、ワークフロー自動化を専門とするソフトウェア開発会社CSMediaProが開発・保守しています。これはAgentic Query Layer (AQL)パターンの最初のリファレンス実装です。

• AQLパターン： https://csmediapro.com/notes/agentic-query-layer
• お問い合わせ先： [email protected]