isu-moodle-mcp

MCP-сервер для подключения Moodle к Claude. Разделён на два уровня:

• Уровень API (18 инструментов, основной): официальный REST API веб-сервисов. Без парсинга HTML, без открытия браузера.

• Уровень CDP (6 инструментов, для закрытых дыр) + уровень старой системы (4 инструмента): debug Chrome используется только тогда, когда API действительно не может получить данные. Самый важный инструмент — probe_course_access() — это единственный способ обнаружить «курс, который ты больше не видишь».

Обычно достаточно только уровня API. Уровень CDP предназначен для вопросов вроде «все ли курсы, которые я вёл, есть в списке?».

Для семинара «Практика ИИ в проектировании курсов» (AIEA) Университета И-Шоу (2026-08-21), модуль 3. Просто склонируйте и адаптируйте под себя — аккаунт GitHub не нужен.

Что это такое

Продемонстрированный на занятии flipclass-mcp — это MCP-сервер для FlipClass Университета Южного Тайваня. У той системы нет API, поэтому она получает данные двумя способами: парсинг HTML (32 xpath) + debug Chrome (матрица оценок, списки участников и другие страницы, которые нельзя прочитать через чистый HTTP). Это демонстрация того, что «даже если система закрыта, имея логин и пароль, можно полностью восстановить её работу».

Этот набор — вторая половина той же задачи: когда у системы есть API, тот же контракт инструментов MCP можно полностью переключить на другой бэкенд.

Названия инструментов и docstring намеренно совпадают в обоих проектах, чтобы можно было напрямую сравнивать, как одна и та же задача выглядит в случае «с API» и «без API».

Related MCP server: Moodle MCP Server

Быстрый старт

1. Получить код

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

Если нет git, на странице GitHub можно нажать Code → Download ZIP.

2. Установить зависимости

pip install -r requirements.txt

Их всего две: requests и mcp.

3. Заменить токен

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

Он спросит логин и пароль от Moodle, и при успехе запишет токен в .env.

Запускайте этот шаг в своём собственном терминале, а не в диалоге с ИИ. Транскрипты диалогов могут сохраняться или резервироваться; если пароль и токен окажутся там — это утечка.

Почему токен, а не логин/пароль? Токен можно отозвать, он привязан только к вашим правам и не приводит к полной компрометации при утечке, в отличие от пароля. Токен Moodle по умолчанию истекает через 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(). Он сообщит, действителен ли токен, какие функции вам реально доступны и чего не хватает. Если что-то не подключается — первым делом запускайте именно его.

Какие есть инструменты

Уровень CDP (сначала запустите python start_debug_chrome_moodle.py и войдите в том окне)

Уровень старой системы (когда школа сменила платформу)

Нужно добавить в .env строку MOODLE_LEGACY_URL=https://адрес-старого-сайта.

В этой версии намеренно нет ни одного инструмента записи (например, mod_assign_save_grade для изменения оценок). Ошибка в read-only инструменте — максимум неверные данные; ошибка в записи — это реальное изменение оценок студентов. Если действительно нужно — добавьте сами, но сначала потренируйтесь на тестовом сайте.

Известные ограничения (обязательно прочитайте этот раздел)

🔴 Старые курсы тихо исчезают — но условия уже, чем вы думаете

core_enrol_get_users_courses возвращает только курсы, на которые у вас сейчас есть активная запись.

Проверено 2026-08-20 на двух локальных Moodle 4.1.18, каждый пункт протестирован:

Эта таблица опровергает очень распространённое утверждение (включая предыдущую версию этого README): «скрытие или архивирование старых курсов заставляет их исчезать». Проверка показала, что это не так. Реально курс исчезает только в последней строке таблицы. Это написано здесь потому, что опровергнутое проверкой утверждение, оставленное в документации, хуже, чем его отсутствие — вы будете действовать по нему и просить у администратора не то.

Курс, студенты и задания остаются в базе данных, просто вы их не видите. А API не сообщает вам «есть курс, который ты больше не видишь» — он просто об этом умалчивает.

Поэтому перед длительным анализом сначала запустите find_hidden_courses() или probe_course_access(course_id) для проверки каждого курса, не полагайтесь только на список из list_history_courses(). Этот инструмент всегда возвращает поле caveat с предупреждением — пожалуйста, не игнорируйте его.

Ошибки Moodle приходят с HTTP 200

Когда Moodle возвращает ошибку, HTTP-статус всё равно 200, ошибка спрятана в поле exception в теле ответа. raise_for_status() её вообще не поймает. Этот сервер уже обрабатывает это, но если вы пишете свой код для работы с Moodle — помните об этом.

accessexception трудно диагностировать

В официальной документации перечислено семь-восемь возможных причин, и если администратор не включил отладку выше уровня NORMAL, сообщение об ошибке не укажет, какая именно причина. Этот сервер переводит её на человеческий язык и даёт три наиболее вероятные причины, но чтобы точно определить, какая из них, всё равно нужно запустить diagnose() и посмотреть, какие функции реально содержит ваш токен.

Вы видите только свои курсы

Это встроенная гарантия Moodle, а не ограничение этого инструмента. Токен полностью наследует права вашей учётной записи, при каждом вызове выполняется проверка прав на уровне контекста. Это одновременно и гарантия безопасности, и ограничение.

Параметры-массивы нельзя передавать в JSON

Moodle REST использует PHP-парсинг $_POST, массивы нужно записывать как courseids[0]=5&courseids[1]=7. Если передать JSON-строку, она будет воспринята как одна строка и вызовет ошибку invalidparameter. Этот сервер автоматически разворачивает массивы.

Имя параметра для скачивания файлов другое

REST-эндпоинт использует wstoken, а webservice/pluginfile.php — token. Это легче всего упустить при переносе. Кроме того, у сервиса должна быть включена опция downloadfiles.

Если get_token.py не работает

По умолчанию Moodle выдаёт право moodle/webservice:createmobiletoken всем вошедшим пользователям, поэтому преподавателю обычно не нужен администратор, чтобы самостоятельно сменить токен. Но школа может изменить это значение по умолчанию — если изменила, вы узнаете об этом только когда реально попробуете сменить токен, снаружи это не обнаружить.

Заметки для разработчиков

Этот проект перенесён из flipclass-mcp. При переносе была вырезана самая болезненная половина и оставлена самая ценная:

• Вырезано (около 247 строк): _login, обработка anticsrf, кэш cookie, обработка множественных входов checkMultiLogin, 32 места парсинга lxml xpath, подключение CDP (debug Chrome)

• Сохранено: каркас FastMCP, сигнатуры и docstring каждого @mcp.tool() ——вот это и есть настоящий актив, потому что это контракт, который видит LLM

Так сделано потому, что ни один готовый Python-пакет для Moodle не подошёл: moodlepy не обновлялся почти два года и жёстко привязан к attrs<23 (версия 2022 года); moodle_api.py не обновлялся три года и отсутствует в PyPI; python-moodle ещё поддерживается, но по сути парсит HTML, а не является REST-клиентом. REST Moodle настолько прост, что пишется за десять-пятнадцать строк, а подключение устаревшего пакета — это просто лишний технический долг.

Лицензия

MIT. Берите и адаптируйте под свою школу, спрашивать разрешения не нужно.