Moodle MCP

Name: Moodle MCP
Author: fabioov

本地服务

github.com/fabioov科研与教育01 周前更新

代码仓库

关于 Moodle MCP

Moodle MCP 是只读服务，可通过自然语言查询 Moodle 课程信息，适合需要查看作业、截止日期、成绩、论坛和通知的学生及其他用户。

主要功能

01列出课程及课程内容
02查看作业截止日期和状态
03读取成绩与反馈
04浏览论坛讨论
05获取近期通知

适用场景

01检查待办作业和截止日期
02查看已提交作业及成绩
03查找课程公告和讨论

MCP 相关

MCP 服务提供只读工具，用于读取 Moodle 站点、课程、作业、成绩、论坛和通知数据。它可通过 stdio 在本地运行，也可作为 HTTP 服务运行。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "fabioov-moodle": {
      "command": "npx",
      "args": [
        "-y",
        "@fabioov/moodle-mcp"
      ],
      "env": {
        "MCP_TRANSPORT": "<MCP_TRANSPORT>",
        "MOODLE_URL": "<MOODLE_URL>",
        "MOODLE_TOKEN": "<MOODLE_TOKEN>"
      }
    }
  }
}

启动命令npx -y @fabioov/moodle-mcp

需要配置的环境变量

MCP_TRANSPORTRun over stdio for local clients

MOODLE_URLRoot URL of your Moodle site, e.g. https://moodle.example.edu

MOODLE_TOKEN密钥Your Moodle web service token (Preferences > Security keys)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@fabioov/moodle-mcp0.1.1stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Moodle MCP

一个开源的、只读 MCP Moodle 服务。将它连接到 Claude，即可用日常语言询问作业、截止日期、成绩、课程、论坛和通知。

与 Moodle Pty Ltd. 无关联，也未获其认可。“Moodle”是其所有者的商标。

可以询问什么

“这个月我还有哪些作业要提交？”
“这周有哪些截止日期？我已经提交了哪些作业？”
“我在机器学习课程中的成绩是多少？”
“我的课程里有新公告吗？”
“显示我的计算机图形学课程的章节和活动。”

工具

所有工具均为只读，并返回简洁易读的结果。

工具	功能	参数
`get_site_info`	验证令牌；查看站点、Moodle 版本和当前用户	–
`list_courses`	你的课程（默认仅显示当前课程）	`includePast?`
`get_course_contents`	查看课程的章节和活动。每个模块都包含 `id` 和 `instance`	`courseId`
`list_assignments`	查看作业及其截止日期，并按截止日期排序	`courseId?`、`upcomingOnly?`、`limit?`（25）
`get_assignment_status`	查看提交/评分状态、成绩和反馈评论	`assignmentId`
`get_upcoming_deadlines`	查看未来 N 天的日历事件和作业；每项作业都会标记为 `submitted` 或 `pending`	`days?`（14）、`onlyPending?`
`get_grades`	查看课程的评分项目	`courseId`
`list_forum_discussions`	查看论坛的近期讨论	`forumId`（`get_course_contents` 返回的 `instance`）
`get_notifications`	查看近期 Moodle 通知	–

要求

已启用 Web Services / 移动应用访问 的 Moodle 站点（Moodle 4.x；本项目基于 4.5 开发）。
你自己的 Web 服务令牌（见下文）。机构禁用的功能只会使对应工具返回错误。
运行服务需要 Node 20+（使用 Wrangler 部署需要 Node 22+），或 Docker，或免费的 Cloudflare 账户。

设置

1. 获取 Moodle URL 和令牌

URL： Moodle 的根地址，不含页面路径或 /webservice，例如 https://moodle.example.edu （如果 Moodle 安装在子目录中，请包含该目录：https://example.edu/moodle）。
令牌： 在 Moodle 中，Preferences → Security keys 会显示 Moodle mobile web service 的密钥。有些站点只会显示标签；点击 Reset 可生成新密钥（并使 Moodle 移动应用退出登录）。或者，如果你使用 Moodle 用户名和密码登录（而非 SSO），可以申请一个令牌： curl -s "$MOODLE_URL/login/token.php" -d username=... --data-urlencode password=... -d service=moodle_mobile_app （请交互式输入密码，以免密码出现在 shell 历史记录中）。

2. 配置

将 .env.example 复制为 .env，并填写 MOODLE_URL、MOODLE_TOKEN 和 MCP_AUTH_SECRET （使用 openssl rand -hex 24 生成后者）。.env 已加入 git 忽略列表。

3. 运行方式，任选其一

Cloudflare Workers（免费、始终运行，无需域名）：推荐

npm ci
npx wrangler login
npx wrangler secret put MOODLE_URL        # https://your.moodle.edu
npx wrangler secret put MOODLE_TOKEN      # your Moodle web service token
npx wrangler secret put MCP_AUTH_SECRET   # openssl rand -hex 24
npm run deploy                            # prints https://moodle-mcp.<you>.workers.dev

请查看 Cloudflare 当前的免费套餐限制。先在本地试运行：将 .env 中的值复制到已加入 git 忽略列表的 .dev.vars，然后运行 npm run dev:worker。

Docker / Node（可自托管）

docker build -t moodle-mcp . && docker run --env-file .env -p 3000:3000 moodle-mcp
# or: npm ci && npm run build && npm start

然后通过 HTTPS 将其公开访问（例如使用 Cloudflare Tunnel 或 Tailscale Funnel）。

仅本地运行（Claude Desktop / Claude Code，stdio）： 无需安装：

MCP_TRANSPORT=stdio MOODLE_URL=https://your.moodle.edu MOODLE_TOKEN=... npx -y @fabioov/moodle-mcp

此模式不需要 MCP_AUTH_SECRET。

4. 将其添加到 Claude

Claude.ai： Settings → Connectors → Add custom connector。URL 为 https://<your-host>/mcp，选择 No sign-in，然后 Add header Authorization = Bearer <MCP_AUTH_SECRET>。
Claude Code： claude mcp add --transport http moodle https://<your-host>/mcp --header "Authorization: Bearer <MCP_AUTH_SECRET>"
如果客户端只能接收 URL，请使用 https://<your-host>/mcp/<MCP_AUTH_SECRET>。请将该 URL 视为密码；首选使用请求头，因为 URL 会被记录到日志中。

安全与隐私

你的令牌代表你本人：任何能够调用你的端点的人，都可以读取该令牌能够读取的内容。请将 MOODLE_TOKEN 和 MCP_AUTH_SECRET 保存在环境变量或 Cloudflare secrets 中，切勿提交到代码库。
该服务在设计上为只读，不提供写入工具。
工具返回的所有内容（成绩、消息、姓名）都会作为对话的一部分发送给 Claude。使用前请查看所在机构关于与第三方服务共享学术数据的规定，尤其是当你能够访问他人的数据时（例如教师）。
如需报告漏洞，请参阅 SECURITY.md。

已知限制

主要使用学生账号在 Moodle 4.5 上进行过测试。教师/管理员角色以及其他版本或插件尚未经过测试；欢迎提交报告和测试夹具。
网站可能会禁用个别 Web 服务功能，因此某些工具可能无法在所有网站上使用。
为节省上下文，大型结果集会被截断（例如，默认最多返回 25 项作业）。

开发

npm ci
npm test            # unit tests with fixtures (no Moodle needed)
npm run typecheck
npm run dev         # HTTP server on :3000 (needs .env)
npm run dev:worker  # Cloudflare Worker locally (needs .dev.vars)

请参阅 CONTRIBUTING.md。变更记录见 CHANGELOG.md。