ntakei-sti/moodle-mcp-server

Moodle MCP Server

このMCPサーバーは、Moodle の API にアクセスして、ユーザーの学習に関するいろんな情報（例: 未提出課題の一覧、履修コース一覧、コース検索など）を返します。

概要

このMCPサーバーは以下の機能を提供します。

• get_resources_under_specific_grade: 成績の回答率が閾値を下回るコースに添付されたファイル情報を取得
• get_my_unsubmitted_assignments: 未提出課題の一覧を取得
• get_my_enrolled_courses: 履修中のコース一覧を取得
• find_my_courses_by_keyword: 全コースからキーワード検索（displayName / summary を含む）
• get_upcoming_deadlines: 指定期間内の締切一覧の課題を取得

動作条件

• Python 3.10+
• MoodleのAPIにアクセスするための権限を持つトークンが発行されていること
• OpenID Connect による ID トークン検証を行う場合は、OIDC プロバイダが JWKS を公開していること

インストール

プロジェクトルートで実行してください。

# 依存パッケージをインストール
pip install -r requirements.txt

環境変数

このプロジェクトは環境変数で各種挙動を制御します。.env ファイルを作成するか、シェルの環境変数として設定してください。通信方式（MCP_TRANSPORT）により必要な環境変数が異なります。

• 共通

  • MOODLE_API_URL (必須): Moodle サイトのベース URL（例: https://moodle.example.com）
  • MOODLE_WSTOKEN (必須): Moodle の Webservice トークン
  • COMPLETION_THRESHOLD (任意): 成績の「回答率」閾値（デフォルト 80）
  • UPCOMING_DEADLINES_DAYS (任意): get_upcoming_deadlines が参照する日数ウィンドウ（デフォルト 7）
  • MCP_TRANSPORT (任意): 通信方式。sse（既定）または stdio

• SSE モード（MCP_TRANSPORT=sse）もしくはStreamable HTTPモード（MCP_TRANSPORT=streamable-http）で主に使用する変数

  • MCP_SERVER_HOST (任意): サーバのバインドアドレス（デフォルト 0.0.0.0）
  • MCP_SERVER_PORT (任意): サーバのポート（デフォルト 8000）
  • ACCEPT_REMOTE_USER_HEADERS (任意): true で X-Remote-User ヘッダを優先（デフォルト true）
  • Bearer トークン検証を使う場合に必要:
    • OIDC_METADATA_URL: OpenID Provider のメタデータ URL（必須）
    • OIDC_AUDIENCE (任意): 期待する audience
    • OIDC_USERNAME_CLAIM (任意): ユーザー識別子に使うクレーム名（デフォルト sub）

• STDIO モード（MCP_TRANSPORT=stdio）で使用する変数

  • REMOTE_USER (必須): 実行中プロセスで扱う Moodle の username

注意: ACCEPT_REMOTE_USER_HEADERS を有効にする場合、リモートヘッダは信頼できるプロキシからのみ渡す ようにしてください。

例: .env ファイルテンプレート（SSEもしくはStreamable HTTP）

MOODLE_API_URL=https://moodle.example.com
MOODLE_WSTOKEN=your_moodle_ws_token
COMPLETION_THRESHOLD=80
OIDC_METADATA_URL=https://idp.example.com/.well-known/openid-configuration
OIDC_AUDIENCE=your-client-id
OIDC_USERNAME_CLAIM=preferred_username
ACCEPT_REMOTE_USER_HEADERS=true
UPCOMING_DEADLINES_DAYS=7
MCP_TRANSPORT=sse
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8000

例: .env ファイルテンプレート（STDIO）

MOODLE_API_URL=https://moodle.example.com
MOODLE_WSTOKEN=your_moodle_ws_token
REMOTE_USER=your-username
MCP_TRANSPORT=stdio

サーバの起動方法

開発環境では以下のコマンドでサーバを起動できます。

python moodle_mcpserver.py

上記を実行すると FastMCP サーバが起動します。既定は SSE で、環境変数で STDIO に切り替えできます。

各ツールの説明

• get_resources_under_specific_grade(ctx):

  • ユーザーの履修コースのうち、成績の回答率が COMPLETION_THRESHOLD を下回るコースに添付されたファイルを列挙します。

• get_my_unsubmitted_assignments(ctx):

  • ユーザーの未提出と判定される課題を検索して返します。課題の提出判定には mod_assign_get_submission_status を優先利用し、 フォールバックで gradereport の情報を参照します。

• get_my_enrolled_courses(ctx):

  • ユーザーが履修しているコース一覧を返します。

• find_my_courses_by_keyword(ctx, keyword):

  • core_course_search_courses を利用して全コースからキーワード検索を行います。表示名（displayname）や概要（summary）も出力に含めます。

• get_upcoming_deadlines(ctx):

  • UPCOMING_DEADLINES_DAYS 日以内に締切が来る課題を集約して返します。mod_assign_get_assignments を優先して使い、 フォールバックで gradereport から締切を探します。

セキュリティと運用上の注意

1. ヘッダベースのユーザー受け渡し:

• X-Remote-User を受け入れる場合は、そのヘッダが信頼できる境界（例: ID プロバイダでトークンを検証したプロキシ）から送信されることを保証してください。直接インターネット経由でヘッダを受け入れるのは危険です。

1. トークン検証:

• サーバ側で ID トークンを検証する場合、OIDC_METADATA_URL から JWKS を取得して署名検証を行います。
• 時刻同期が崩れていると期限検証で失敗するため、サーバの NTP を確認してください。

STDIO モードでのユーザー識別

STDIO では HTTP ヘッダが利用できないため、環境変数 REMOTE_USER に設定した Moodle の username を用いてユーザーを決定します（リクエスト毎の切替は不可、プロセス全体で固定）。