moodle-mcp

English | 繁體中文 | 简体中文 | 日本語 | Español | Deutsch | Português | Français

一个 Model Context Protocol 服务，让 大模型 Agent 能够使用真实的 Moodle LMS——通过单个静态二进制文件读取课程、获取作业 PDF、 编写代码、上传并提交作业。

mcp-name: io.github.G36maid/moodle-mcp

使用 Rust 和官方 MCP SDK（rmcp）构建。 已在 Moodle 3.7、4.5 和 5.2 上进行实时验证；专为 3.7 → 5.x 设计。

✅ 为什么选择它

通用聊天机器人无法访问你的 Moodle，因此每项学习任务都只能手动完成——打开五个浏览器标签页来回答*“这周要交什么？”*，手动重新上传 PDF，一页一页地复制论坛内容和成绩。

moodle-mcp 会让 Agent 以你的身份登录。20 个类型化工具覆盖完整的学生学习流程，Agent 可以自行串联调用——无需打开浏览器：

• 开箱即用——一个二进制文件集成文档转换、HTML → Markdown、身份验证 CLI 和可选的备用通道：无需插件、辅助脚本或第二套运行时
• 为 Agent 原生设计——工具接收并返回本地文件路径，而不是 base64；每个结果都包含下一次调用所需的 ID；错误信息通俗易懂，并会建议修复方法
• 默认安全——写入工具会先征求你的确认；提交内容会保持为草稿，直到你确认；有意不提供测验答题功能
• 适配不同版本——已在 Moodle 3.7 上验证，并针对 4.x/5.x 设计；不同版本的响应差异会自动处理
• 单个静态二进制文件——无运行时依赖

🚀 快速开始

需要一个 Moodle 3.7 → 5.x 账户，并且网站允许移动应用 Web 服务（大多数网站都允许——请参阅 先决条件）。

# 1. Install
cargo install moodle-mcp        # or a prebuilt binary / one-click .mcpb — no Rust needed

# 2. Log in once — prints MOODLE_URL and MOODLE_TOKEN
moodle-mcp auth

# 3. Connect your client (Claude Code shown; Codex/OpenCode/pi below)
claude mcp add moodle \
  --env MOODLE_URL=https://moodle.example.com \
  --env MOODLE_TOKEN=your-token \
  -- /path/to/moodle-mcp

# 4. Open a chat and ask:
#    "What's due in the next two weeks? Plan my studying around it."

也可以将以下内容粘贴到你的 Agent 中，让它自动完成所有步骤（它会在终端中打开 moodle-mcp auth——请在那里输入学校账户凭据）：

Set up moodle-mcp (github.com/G36maid/moodle-mcp): read docs/src/installation.md
and docs/src/configuration.md from the repo's main branch first. Then install
the binary for my platform, run `moodle-mcp auth` in the terminal so I can
type my school credentials when it prompts, and register the server in your
own MCP config using the snippet for your harness. Never store or repeat my
credentials; ask before anything global.

预编译二进制文件、SSO 登录、适用于各客户端的配置片段，以及完整的环境变量参考： 安装 · 入门指南 · 配置

💬 Agent 能做什么

无需其他设置即可使用所有这些功能——Agent 会根据工具描述发现工具，并自行串联调用：

你说	Agent 串联调用
“帮我完成信息安全 HW1：阅读作业说明和附件 PDF，解答题目，并提交草稿。”	get_assignment（说明和附件）→ fetch_file（PDF → Markdown，包含数学公式）→ 解答题目 → 写入答案文件 → upload_file → submit_assignment → get_assignment（验证已提交 ✓）
“根据即将到来的截止日期和课程资料，为我制定一份接下来两周的完整学习计划。”	get_schedule（所有截止日期）→ 按课程调用 get_course_overview → 制定按天安排、兼顾截止日期的计划
“我没跟上这周数据通信课的内容——帮我补上，包括公告论坛。”	get_notifications + get_forum_discussions → get_discussion_posts → 综合整理每周摘要
“帮我准备软件工程测验：老师发了什么相关内容？”	get_course_overview（测验条目）→ get_assignment（要求）→ 相关论坛主题

🔄 Agent 的工作方式

这些工具模拟了你在 Moodle 中的浏览方式——每一层的输出都包含下一层所需的 ID：

flowchart TD
    Q["💬 prompt (intent only)"] --> LC["list_courses(search?)<br/>find the course"]
    LC --> OV["get_course_overview(course_id)<br/>markdown map: sections · files ·<br/>assignments · quizzes · forums · grades"]
    OV --> FD["get_forum_discussions(forum_id)<br/>→ get_discussion_posts(discussion_id)"]
    OV --> AS["get_assignment(assignment_id)<br/>brief · attachments · submission · grade"]
    AS --> FF["fetch_file(url)<br/>assignment PDF → readable markdown"]
    FF --> WK["agent works:<br/>answers · code · report on disk"]
    WK --> UP["upload_file(path, filename)<br/>solution → draft area → item_id"]
    UP --> SB["submit_assignment(assignment_id, item_id?, finalize?)<br/>save draft or turn in"]
    SB --> VF["get_assignment<br/>verify: submitted ✓ files ✓"]
    OV --> SC["get_schedule(time window)<br/>deadlines → study plan"]
    OV --> GR["get_grades(course_id)<br/>graded items + feedback"]

专用工具未覆盖的内容，都可以通过 call_ws_function + list_ws_functions 这一备用方式访问——涵盖典型令牌可调用的约 350 个函数（共 22 个：20 + 2；备用方式需通过 MOODLE_ENABLE_WS_FUNCTION=true 启用）。

📚 文档

完整文档位于 moodle.ntnu.cc/docs（mdBook——可运行 mdbook serve docs 在本地阅读）：

页面	内容
入门指南	从零开始发出第一个提示词；无需 MCP 使用经验
安装	预构建二进制文件、cargo、从源代码安装
配置	所有环境变量；Claude Code、Codex、OpenCode 和 pi 的配置片段
工具	完整的 22 个工具参考，以及它们之间的 ID 流转
安全与身份验证	令牌生命周期、传输和写入安全
更新日志	各版本的发行说明
开发	架构介绍、测试、发布流程
关于	moodle-mcp、MCP 和 Moodle 简介

🧰 开发

cargo test                 # unit + wiremock integration + MCP protocol tests
cargo clippy --all-targets
cargo fmt -- --check
cargo build --release

项目文档位于 docs/——使用 mdBook 编写，并由 Prettier 格式化（参见 docs/README.md）；运行 mdbook serve docs 预览。

着陆页位于 site/——使用 Astro 7 + TypeScript 构建（运行 cd site && npm install && npm run dev，使用 npm run build 构建）。

🔐 安全

请使用 HTTPS——每个请求都会携带令牌。令牌不会出现在工具输出或错误中，只会注入同站点的 Moodle URL；写入工具在执行前会向你确认。详情请参阅： 安全与身份验证。

📄 许可证

MIT——参见 LICENSE。