moodle-mcp

Moodle MCP 服务

一个基于 Moodle Web 服务 REST API 的 MCP 服务，供 AI 助手（Claude Code、Cursor、Codex 和其他 stdio 客户端）使用。它专为教师打造：助手可以查看课程、作业和学生提交内容，下载提交文件，并在教师确认后，以教师身份保存成绩和反馈。与面向学生的 Moodle MCP 服务不同，此服务专注于作业审阅和评分。

只要 Moodle 站点启用了移动端 Web 服务（moodle_mobile_app），此服务就能使用：令牌的签发方式与 Moodle 移动应用相同，因此通过外部 OAuth 提供商登录时，即使需要验证码也能正常使用。

前提条件

• Node.js ≥ 22。
• Google Chrome 或 Chromium，用于运行 moodle-mcp-login 命令。
• Moodle 站点已启用移动应用访问权限（Site administration → Mobile app）。 检查方法：打开 <site>/admin/tool/mobile/launch.php，应能正常打开，而不是返回错误。

快速开始

以下示例使用 https://moodle.example.org；请将其替换为浏览器地址栏中显示的 Moodle 地址（协议、主机、路径；末尾的斜杠无关紧要）。

1. 登录：每台机器登录一次；之后每当工具返回登录错误时都要重新登录 （Moodle 登录和服务端令牌，俄语）：

   MOODLE_URL=https://moodle.example.org npx -y -p @av-leschinskiy/moodle-mcp moodle-mcp-login
   

   Chrome 窗口会打开：像平常一样登录站点并自行完成验证码。命令会显示 Logged in as <name> on <site>，然后关闭窗口。如果不加 -p，npx 会启动服务，而不是登录命令。Chrome 会从 PATH 中查找；在 macOS 和 Windows 上，请在 MOODLE_CHROME 中设置其路径。

2. 将服务添加到客户端。Claude Code：

   claude mcp add moodle -e MOODLE_URL=https://moodle.example.org -- npx -y @av-leschinskiy/moodle-mcp
   

   添加 -s user 可为所有项目启用；不添加则仅对当前项目启用。

   Codex：使用命令，或在 ~/.codex/config.toml 中添加配置块：

   codex mcp add moodle --env MOODLE_URL=https://moodle.example.org -- npx -y @av-leschinskiy/moodle-mcp
   

   [mcp_servers.moodle]
   command = "npx"
   args = ["-y", "@av-leschinskiy/moodle-mcp"]
   env = { MOODLE_URL = "https://moodle.example.org" }
   

   Cursor 和其他客户端：配置一个 stdio 服务，命令为 npx -y @av-leschinskiy/moodle-mcp，并设置 MOODLE_URL 变量：

   {
     "mcpServers": {
       "moodle": {
         "command": "npx",
         "args": ["-y", "@av-leschinskiy/moodle-mcp"],
         "env": { "MOODLE_URL": "https://moodle.example.org" }
       }
     }
   }
   

3. 检查：让助手“显示我的 Moodle 课程”。

从仓库克隆目录运行时，请使用 node <clone>/dist/index.js 和 node <clone>/dist/cli/login.js 代替 npx：dist/ 已提交，无需构建。

包含内容

共有10 个工具；其中 3 个需要用户确认。

类别	工具	确认	涵盖内容
站点	2	—	我的身份、Moodle 版本、可用功能、我的课程
作业和提交内容	4	—	课程作业、参与者和提交状态、整个课程中需要教师处理的事项、完整提交内容
文件	1	—	将提交文件下载到磁盘
评分	3	3	成绩和反馈、提交评论、退回提交以供修改

完整名称列表

站点

• moodle_list_courses
• moodle_site_info

作业和提交内容

• moodle_get_submission
• moodle_list_assignments
• moodle_list_pending_submissions
• moodle_list_submissions

文件

• moodle_download_file

评分

• moodle_add_submission_comment — 需确认
• moodle_revert_submission_to_draft — 需确认
• moodle_save_grade — 需确认

此服务代表你执行操作：它能查看和更改你在 Moodle 界面中能查看和更改的相同内容。宿主仅会要求确认学生可见的写入操作：保存成绩和反馈、添加提交评论、将提交退回草稿状态（destructiveHint: true）。下载文件也会执行写入操作，但只写入你的磁盘，因此无需确认。

为节省模型上下文，响应内容会经过精简：描述和提交内容中的 HTML 会转换为纯文本，时间会转换为 ISO 格式；未设置的成绩会转换为 null，并且绝不会返回参与者的电子邮件地址。

配置

变量	必需	默认值	说明
MOODLE_URL	是	—	Moodle 站点地址（wwwroot），例如 https://moodle.example.org
MOODLE_TOKEN_FILE	—	~/.config/mcp-moodle/token.json	moodle-mcp-login 保存令牌的位置（通过 homedir() 解析路径）
MOODLE_TOKEN	—	—	覆盖 Web 服务令牌（CI / 冒烟测试）
MOODLE_TIMEOUT	—	30000	单次 API 请求的超时时间（毫秒）
MOODLE_CHROME	—	—	moodle-mcp-login 使用的 Chrome/Chromium 二进制文件（默认在 PATH 中查找）
MOODLE_DEBUG	—	false	设置为 1/true/yes/on 时，会向 stderr 输出调试信息，并在主机日志通道中启用 debug 级别

令牌文件的权限为 0600，并会保存签发令牌的站点地址：如果该地址与 MOODLE_URL 不匹配，服务会提示你运行 moodle-mcp-login。服务会在每次请求时读取此文件，因此重新登录后无需 重启主机。错误消息、日志和工具响应（包括文件 URL）中的令牌都会被清除。

登录时使用的 Chrome 配置文件与主配置文件分开保存 （~/.config/mcp-moodle/chrome-profile）：站点 Cookie 会保留，因此通常无需密码 即可重新登录。

开发

npm install        # also enables the git hooks (.githooks)
npm run dev        # tsx, no compilation
npm run build      # native TypeScript 7 → dist/
npm run verify     # typecheck + lint + tests + docs check
MOODLE_URL=… npm run smoke   # read-only tool chain against a live Moodle

仅使用 npm run build 构建：devDependencies 中包含两个编译器版本， 详情。dist/ 已提交；提交前钩子会构建并暂存该目录、 递增补丁版本，并重新生成上方的表格。 架构和规则见 AGENTS.md（俄语）。