moodle-mcp

用于 Moodle 的模型上下文协议 (MCP) 服务器。使 AI 智能体能够通过 Web 服务在 Moodle 中发布和管理教学内容（课程、资源、活动），并保证幂等性。

npm license: MIT

状态： v0.1 MVP。

它是什么

moodle-mcp 是一个基于 stdio 的 MCP 服务器，它公开了一组小型的高级外观 (facades) 以及一个低级 ws_raw 原语，用于将规范的教学“Ficha”（带有 YAML 前置元数据的 markdown 文件）发布到 Moodle 课程中，作为实际的章节、页面、资源和活动。每次写入都通过 idnumber 进行更新插入 (upsert)，因此重新发布相同的 Ficha 永远不会创建重复项。

主要消费者：驱动 Italicia 语言教学工作流的 Claude Desktop。但它是一个通用的开源适配器——任何支持 MCP 的智能体 + 任何启用了 Web 服务的 Moodle 4.x/5.x 实例都可以使用它。

v0.1 中公开的工具

工具	用途
`obtener_contexto_curso`	课程快照：元数据、章节、最近通过 MCP 发布的课程、注册人数。
`publicar_ficha_clase`	将 FichaClase（绝对 markdown 路径）发布为 Moodle 章节 + 模块更新。
`publicar_preview`	与上述相同，但强制隐藏 + 返回预览 URL。
`confirmar_preview`	使之前隐藏的章节及其模块对学生可见。
`ws_raw`	逃生舱：直接调用任何 Moodle WS 函数。

v0.1 中未包含（计划在 v0.2+ 中实现）：publicar_ficha_examen、sync_alumnos_csv、HTTP/SSE 传输、GIFT 构建器、多部分资产上传、自动模块创建。

安装

# Via npx (recommended for Claude Desktop)
npx -y @marcosnahuel/moodle-mcp

# Or install globally
npm install -g @marcosnahuel/moodle-mcp

需要 Node.js 20 或更高版本。

配置（环境变量）

变量	必需	默认	描述
`MOODLE_URL`	是	—	Moodle 实例的完整 HTTPS URL。
`MOODLE_WS_TOKEN`	是	—	具有编辑权限的 Web 服务令牌。
`MOODLE_WS_TIMEOUT_MS`	否	`30000`	每个请求的超时时间。
`MOODLE_WS_MAX_RETRIES`	否	`3`	瞬时故障时的重试次数。
`MOODLE_WS_RATE_LIMIT_PER_SEC`	否	`10`	令牌桶速率限制。
`MCP_LOG_LEVEL`	否	`info`	`error` / `warn` / `info` / `debug`。
`MOODLE_ALLOW_INSECURE`	否	`false`	允许 `http://` URL（仅限开发环境的逃生舱）。

Claude Desktop 配置

添加到 claude_desktop_config.json（请参阅 examples/setup-claude-desktop.md 获取各操作系统的确切路径）：

{
  "mcpServers": {
    "moodle": {
      "command": "npx",
      "args": ["-y", "moodle-mcp"],
      "env": {
        "MOODLE_URL": "https://your-moodle.example.com",
        "MOODLE_WS_TOKEN": "your-ws-token"
      }
    }
  }
}

重启 Claude Desktop。上述五个工具现在应该对智能体可用。

示例

1. 在操作前获取课程快照

// tool call
{
  "name": "obtener_contexto_curso",
  "arguments": { "course_id": 42, "incluir_ultimas_clases": 5 }
}

响应（摘要）：

{
  "course": { "id": 42, "fullname": "Italiano A1", "shortname": "ITA-A1", "format": "topics", "startdate": 1700000000 },
  "secciones": [{ "id": 100, "name": "Unidad 3", "section": 3, "visible": true, "modules_count": 6 }],
  "ultimas_clases": [{ "seccion_id": 100, "seccion_name": "Unidad 3", "ficha_idnumber": "mcp:a9993e364706816aba3e2571" }],
  "matriculados": { "total": 18, "docentes": 1, "alumnos": 17 }
}

2. 发布 FichaClase（先预览）

{
  "name": "publicar_preview",
  "arguments": {
    "ficha_path": "/home/alicia/fichas/italiano/a1-2026/u3/c5.md",
    "course_id": 42
  }
}

响应包含 Alicia 可以打开以进行审查的 preview_url。一旦批准：

{
  "name": "confirmar_preview",
  "arguments": { "seccion_id": 100, "recursos_ids": [501, 502, 503] }
}

3. 逃生舱 — 调用原始 WS 函数

{
  "name": "ws_raw",
  "arguments": {
    "function_name": "core_webservice_get_site_info",
    "params": {}
  }
}

响应：

{ "data": { "sitename": "Aula Italicia", "release": "5.0.2+", ... } }

幂等性

此 MCP 创建的每个资源都带有格式如下的稳定 idnumber：

mcp:<first 24 chars of sha1(ficha.id + "|" + component_id)>

重新发布相同的 Ficha 会通过 idnumber 找到现有资源并就地更新。不会产生任何重复。在任何地方、任何时间重试都是安全的。

v0.1 注意事项

v0.1 对其能力边界是诚实的。它可靠地：

查找课程及其章节和模块。
通过 mcp: idnumber 前缀查找“拥有的”资源。
更新现有模块的可见性（预览 → 确认工作流）。
显示带有稳定 code 字段的结构化 Moodle 错误。
从不记录令牌，从不传播堆栈跟踪。

v0.1 尚不支持：

通过多部分上传将资产文件上传到 Moodle 草稿文件区域。计划用于资产上传的调用会在 advertencias 中报告——第一次手动植入它们。
通过 Web 服务创建全新的章节或模块。如果模块尚不存在，该工具会返回状态 "missing" 以及一条 advertencia。安装 local_wsmanagesections（或等效插件）并连接这些端点是 v0.2 的工作。

这两个差距都是由 tests/integration/ 中的集成套件在针对真实的 Moodle docker 运行时驱动的。

开发

git clone https://github.com/marcosnahuel/moodle-mcp
cd moodle-mcp
npm install

npm run typecheck         # tsc --noEmit
npm test                  # vitest unit suite
npm run test:coverage     # with v8 coverage (≥80% enforced)
npm run build             # tsup → dist/

# Integration — requires docker
docker compose -f tests/integration/docker-compose.test.yml up -d
export MOODLE_TEST_URL=http://localhost:8081
export MOODLE_TEST_TOKEN=<generate in Moodle admin>
export MOODLE_TEST_COURSE=<course id>
npm run test:integration
docker compose -f tests/integration/docker-compose.test.yml down -v

安全性

令牌永远不会被记录。出现在任何日志记录的任何字段中的令牌都会被替换为 ***。
错误消息中的 URL 也会被脱敏。
除非设置了 MOODLE_ALLOW_INSECURE=true（仅限开发），否则必须使用 HTTPS。
MCP 仅通过 Web 服务 REST 与 Moodle 通信。没有 cookie 认证，没有网页抓取，没有直接数据库访问。

贡献

请参阅 CONTRIBUTING.md 了解问题、PR 和提交约定。

参与本项目即表示您同意遵守 CODE_OF_CONDUCT.md。

moodle-mcp

moodle-mcp

它是什么

v0.1 中公开的工具

安装

配置（环境变量）

Claude Desktop 配置

示例

1. 在操作前获取课程快照

2. 发布 FichaClase（先预览）

3. 逃生舱 — 调用原始 WS 函数

幂等性

v0.1 注意事项

开发

安全性

贡献

许可证

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API