isu-moodle-mcp

Moodle を Claude に接続する MCP server。2 層構成：

• API 層（18 本、主力）：公式 Web Service REST API。HTML をスクレイピングしない、ブラウザを開かない。

• CDP 層（6 本、穴埋め）＋旧システム層（4 本）：API では本当に取得できない場合のみ debug Chrome を使用。 最も重要なのは probe_course_access() —— これは「もう見えなくなった授業がある」ことを発見できる唯一の方法。

普段は API 層だけで十分。CDP 層は「自分が教えた授業が全部リストにあるか」といった質問のために用意している。

義守大学 AIEA「課程設計 AI 実務」ワークショップ（2026-08-21）ユニット 3 用。 そのまま pull して自分のものに書き換えてください、GitHub アカウントは不要。

これは何か

授業でデモする flipclass-mcp は南台科技大学 FlipClass の MCP server。あのシステムには API がないので、 データ取得は 2 つの方法に頼っている：HTML スクレイピング（32 箇所の xpath）＋ debug Chrome（成績マトリクス、メンバー名簿など 純粋な HTTP では読めないページ）。これは「システムがどんなに閉じていても、アカウントとパスワードがあれば完全にリバースエンジニアリングできる」ことのデモ。

こちらは同じことのもう半分：相手に API がある場合、同じ MCP tool 契約のままでバックエンドを丸ごと差し替えられる。

tool 名と docstring は両者で意図的に同じにしているので、そのまま見比べて、同じ要件が 「API あり」と「API なし」の 2 つのケースでそれぞれどうなるか確認できる。

Related MCP server: Moodle MCP Server

クイックスタート

1. コードを取得

git clone https://github.com/scatjay/isu-moodle-mcp.git

git がなくても GitHub のページで Code → Download ZIP を押せば OK。

2. 依存パッケージをインストール

pip install -r requirements.txt

2 つだけ：requests と mcp。

3. token を取得し直す

python get_token.py https://moodle.你的學校.edu.tw

Moodle のアカウントとパスワードを聞かれるので、成功すると token が .env に書き込まれる。

この手順は自分のターミナルで実行してください。AI の会話内では実行しないでください。 会話の逐語録は保存・バックアップされる可能性があり、パスワードや token がそこに載ると漏洩したも同然です。

なぜアカウント/パスワードではなく token なのか？ token は失効させられるし、自分の権限にだけ紐づくし、パスワードのように 一度漏れたら全滅、ということはない。Moodle の token はデフォルトで 12 週間で期限切れ——学期の途中でツールが突然壊れて invalidtoken と言われたら、戻ってこのスクリプトを再実行すればいい。

4. Claude に接続

Claude Desktop の設定ファイル（claude_desktop_config.json）に追加：

{
  "mcpServers": {
    "moodle": {
      "command": "python",
      "args": ["C:/你的路徑/isu-moodle-mcp/server.py"],
      "env": {
        "MOODLE_URL": "https://moodle.你的學校.edu.tw",
        "MOODLE_TOKEN": "貼上 .env 裡那一串",
        "MOODLE_LEGACY_URL": "https://舊站網址（沒有舊站就整行刪掉）"
      }
    }
  }
}

5. まずヘルスチェックを実行

接続したら、最初に Claude に diagnose() を実行させる。token が有効かどうか、 実際にどの関数を呼び出せるか、何が足りないかを教えてくれる。接続できないとき、最初に実行すべきはこれ。

ツール一覧

CDP 層（先に python start_debug_chrome_moodle.py を実行し、そのウィンドウでログインする必要あり）

旧システム層（学校がプラットフォームを切り替えた場合用）

.env に MOODLE_LEGACY_URL=https://旧サイトのURL を 1 行追加する必要がある。

このバージョンには意図的に書き込みツールを一切含めていない（例：成績を変更する mod_assign_save_grade）。 読み取り専用のものが間違っていても、せいぜいデータが正しくないだけ。書き込みが間違うと、本当に学生の成績を変更してしまう。 本当に必要なら自分で追加してよいが、まずテストサイトで練習すること。

既知の制限（この節は必ず最後まで読むこと）

🔴 古い授業は静かに消える——ただし条件は思ったより狭い

core_enrol_get_users_courses は**「現在も履修関係がある」授業だけ**を返す。

2026-08-20 に 2 台のローカル Moodle 4.1.18 で実測し、項目ごとに検証済み：

この表はよくある説（この README の前の版も含む）を覆す： 「非表示やアーカイブされた古い授業は消える」。実測では成立しない。 実際に授業が消えるのは最後の行だけ。 ここに書いたのは：実測で覆された説がドキュメントに残っているのは、書かないより悪いから—— それを信じて管理者に間違った要求をしてしまうことになる。

授業・学生・課題はすべてデータベースに残っている。ただ見えなくなっているだけ。そして API は 「見えなくなった授業がある」ことを教えてくれない。ただ言及しないだけ。

だから長期間の分析をする前に、まず find_hidden_courses() か probe_course_access(course_id) で 1 つずつ探査すること。list_history_courses() のリストだけを信じてはいけない。 あのツールは必ず caveat フィールドで注意を促してくる。無視しないこと。

Moodle のエラーは HTTP 200

Moodle がエラーを返すときも HTTP ステータスコードは 200 のままで、エラーは body の exception フィールドに隠れている。 raise_for_status() ではまったく検出できない。この server は処理済みだが、自分で Moodle を叩くプログラムを書くときは覚えておくこと。

accessexception は原因の特定が難しい

公式に挙げられている原因は 7〜8 種類あり、管理者が debug を NORMAL 以上に設定していない限り、 エラーメッセージはどの原因かを教えてくれない。この server はそれを平易な言葉に翻訳し、可能性の高い 3 つの原因を提示するが、 本当にどれかを確定するには、やはり diagnose() を実行して自分の token にどの関数が含まれているか確認する必要がある。

自分の授業しか見えない

これは Moodle の組み込みの保証であり、このツールの制限ではない。token は完全に本人の権限を継承し、 呼び出しのたびに context レベルの権限チェックが行われる。これは同時に安全の保証であり、制限でもある。

配列パラメータは JSON にできない

Moodle REST は PHP の $_POST で解析するため、配列は courseids[0]=5&courseids[1]=7 のように書く必要がある。 JSON 文字列を渡すと単一の文字列として扱われ、invalidparameter エラーになる。この server は自動で平坦化済み。

ファイルダウンロードのパラメータ名が違う

REST エンドポイントは wstoken を使うが、webservice/pluginfile.php は token を使う。 移植時に最も見落としやすい点。しかもサービスの downloadfiles が有効になっている必要がある。

get_token.py が失敗する場合

Moodle のデフォルトでは moodle/webservice:createmobiletoken がすべてのログインユーザーに付与されているため、 教員は通常、管理者なしで自分で token を交換できる。ただし学校はこのデフォルト値を変更できる—— 変更されていた場合、実際に交換しようとしたときに初めて気づく。外から探知することはできない。

開発メモ

これは flipclass-mcp から移植したもの。移植時に削ったのは最も痛い半分、残したのは最も価値のある半分：

• 削除（約 247 行）：_login、anticsrf 処理、cookie キャッシュ、checkMultiLogin 多重ログイン処理、32 箇所の lxml xpath 解析、CDP（debug Chrome）接続

• 保持：FastMCP の骨格、各 @mcp.tool() のシグネチャと docstring ——これこそが本当の資産。なぜならそれが LLM が見る契約だから

こうしたのは、既存の Moodle Python パッケージがどれも使えなかったから：moodlepy は更新が約 2 年止まっており 依存を attrs<23（2022 年版）に固定している；moodle_api.py は更新が 3 年止まりで PyPI にもない； python-moodle はまだメンテナンスされているが、REST クライアントではなく HTML スクレイピング。 Moodle REST は十数行で書き終わるほど単純で、更新停止パッケージを入れるのは技術負債を背負うだけ。

ライセンス

MIT。自分の学校のバージョンに書き換えて使ってください。許可を求める必要はありません。