moodle-mcp-server-aql

moodle-mcp-server — AI 驱动的 LMS 分析

向你的 Moodle 实例提问，即可在几秒内获得结构化答案。

moodle-mcp-server 是一个开源 MCP（Model Context Protocol）服务，可将 AI Agent 直接连接到 Moodle 的 Web Services API。它是 Agentic Query Layer (AQL) 模式的首个参考实现——这是一种软件设计模式，旨在让大模型安全地、基于权限且以只读方式访问结构化数据。

无需学习报表生成器、编写 SQL 或导出 CSV，只需用通俗的英语提问，AI Agent 就会查询你的 LMS 并返回结构化数据。

AQL 模式： https://csmediapro.com/notes/agentic-query-layer 项目主页： https://csmediapro.com/products/moodle-mcp-server npm 包： https://www.npmjs.com/package/moodle-mcp-server-aql MCP Registry： io.github.csmediapro/moodle-mcp-server-aql

---

功能

• 核心查询工具 — 课程目录、用户选课、作业、分类导航、站点元数据、用户查找和缓存管理
• 高级报告插件 — 可通过插件运行时附加课程完成情况报告、近期活动等可选工具
• 与 LLM 无关 — 可与 Claude、GPT、Gemini、Ollama 或任何兼容 MCP 的 AI 客户端搭配使用
• 无需修改 LMS — 使用 Moodle 现有的 Web Services API，无需安装插件
• 满足合规要求的数据处理 — 以隐私保护为设计原则，安全、高效地处理数据
• 只读 — 从不修改 Moodle 数据，可安全用于生产环境
• 可扩展插件 — 将新的工具模块放入目录即可；工具和可选的 Agent 路由提示会在运行时自动注册

---

快速开始

前置条件

• Node.js 20+
• 已启用 Web Services 的 Moodle 实例
• Moodle API 令牌（站点管理 → 插件 → Web services → 管理令牌）

配合 MCP 客户端使用

大多数用户会通过 Claude Desktop 等 MCP 客户端启动服务：

{
  "mcpServers": {
    "moodle-mcp-server-aql": {
      "command": "npx",
      "args": ["-y", "moodle-mcp-server-aql"],
      "env": {
        "MOODLE_URL": "https://your-moodle-instance.example",
        "MOODLE_TOKEN": "your-moodle-web-services-token"
      }
    }
  }
}

从源代码设置

# Clone the repo
git clone https://github.com/csmediapro/moodle-mcp-server
cd moodle-mcp-server

# Install dependencies
npm install

# Configure
cp packages/server/.env.example packages/server/.env
# Edit .env: add your MOODLE_URL and MOODLE_TOKEN

# Run (stdio mode)
npm run server:build
node packages/server/dist/index.js

用户字段架构

用户字段显示设置会针对每个 Moodle 实例生成，并在本地保存到 packages/server/data/user-field-schema.json。此文件有意从 git 中忽略， 因为其中可能包含特定站点的自定义个人资料字段。

连接到 Moodle 站点后，运行一次 refresh_user_field_schema 工具， 以发现可用的标准用户字段和自定义用户字段。最简示例结构见 packages/server/data/user-field-schema.example.json。

单独安装的插件可以使用此架构，将自定义个人资料字段展平为稳定键名， 例如 school。例如，高级 user-directory 插件会使用它来缓存和汇总 完整用户目录字段，这些操作均在 OSS 核心之外进行。

配置标识

核心包含两个不同的服务标识字段：

• server.id — 稳定的机器标识，例如 mcp_8f3k2q9x
• server.name — 面向用户的显示名称

如果缺少 server.id，核心会生成一个，并在继续启动前将其写入解析后的配置文件。

环境变量覆盖项：

• MOODLE_MCP_CONFIG 或 MOODLE_MCP_SERVER_CONFIG — 指定配置文件路径
• SERVER_ID — 显式覆盖 server.id
• SERVER_NAME — 显式覆盖 server.name
• SERVER_VERSION — 显式覆盖 server.version

如果缺少 server.id，且解析后的配置路径不可写，启动会有意失败。

使用参考客户端

# From the project root
cp packages/client/.env.example packages/client/.env
npm run client:dev
# Open http://localhost:3000

客户端会自动检测你的 Moodle 实例，并显示聊天界面，你可以用通俗的英语提问。

---

连接大模型

moodle-mcp-server 需要 AI 模型来驱动自然语言界面。模型由你提供——moodle-mcp-server 核心和参考客户端支持任何兼容 MCP 的服务提供商。

选项 1：本地运行（速度与隐私优先推荐）

本地运行模型可将所有数据保留在自己的硬件上——不会有任何数据离开你的网络。现代量化模型在消费级 GPU 上运行良好，甚至也能在仅使用 CPU 的配置上运行。

**性能：**在单张 RTX 3090 上运行量化后的 24B 模型，首次查询后响应时间约为 1.5 秒——系统初始化完成后，速度比大多数云 API 更快。

通过 Ollama（最简单）

# Install Ollama: https://ollama.com
ollama pull gemma3:12b      # Fast, reliable tool use (~200ms TTFT)
ollama pull qwen3:14b       # Strong reasoning, good for complex queries
ollama pull deepseek-r1:14b # Excellent at multi-step chains

然后将参考客户端指向 http://localhost:11434（Ollama 的默认地址）。

通过 llama.cpp（控制力最强）

# Download a GGUF model (example: Devstral 24B Q4)
# Run the llama.cpp server:
llama-server -m devstral-24b-Q4_K_M.gguf --ctx-size 60000 --port 8080

将参考客户端指向 http://localhost:8080/v1。

推荐的本地模型

模型	大小	最适合	硬件
Gemma 3 12B	~7 GB VRAM	快速调用工具、简单查询	单张消费级 GPU
Qwen 3 14B	~8.5 GB VRAM	复杂推理、多工具链	单张消费级 GPU
Devstral 24B Q4	~14.5 GB VRAM	能力最强、60K 上下文	RTX 3090 / 4090

选项 2：云服务提供商

Anthropic（Claude）：

export ANTHROPIC_API_KEY=sk-ant-...

在参考客户端的服务提供商下拉菜单中选择“Anthropic”。Claude Sonnet 的工具调用行为最可靠。

OpenAI（GPT）：

export OPENAI_API_KEY=sk-...

在服务提供商下拉菜单中选择“OpenAI”。GPT-4o 处理结构化查询的表现良好。

Ollama Cloud： 使用与本地 Ollama 相同的 API，托管于 https://ollama.com/v1。这是一个不错的折中方案——比本地冷启动更快，也比大型云服务提供商更注重隐私。

选项 3：Claude Desktop（直接使用 MCP）

Claude Desktop 通过 stdio 直接连接到 moodle-mcp-server 核心——无需参考客户端。

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "moodle-mcp-server": {
      "command": "node",
      "args": ["/path/to/moodle-mcp-server/packages/server/dist/index.js"],
      "env": {
        "MOODLE_URL": "https://your-moodle-instance.com",
        "MOODLE_TOKEN": "your-api-token"
      }
    }
  }
}

重启 Claude Desktop。服务器的工具将显示在 Claude 的工具列表中——可以直接提问。

---

工具

核心工具（免费、开源 — AGPL）

工具	说明
list_courses	完整课程目录，支持按类别逐层查看
get_course	查看任意课程的详细信息
list_course_users	已选课用户及其角色和访问数据（现已支持按课程名称搜索并交互式选择）
list_assignments	所有作业及其截止日期
list_categories	完整层级结构，可精确解析父级
get_site_info	实例概览——站点名称、版本、课程数量
get_user	查看 Moodle 用户的详细信息
list_user_courses	指定用户的课程
search_users	按 Moodle 标准身份字段搜索用户
search_courses_by_name	按名称搜索课程，支持部分匹配和交互式选择

高级插件（单独提供）

• 高级报告 — 成绩册、跨课程比较、自定义报告生成器
• 用户分析 — 进度跟踪、参与度评分、风险标记
• 用户目录 — 缓存的目录列表，以及对标准和自定义个人资料字段进行结构化筛选
• 合规套件 — 认证跟踪、过期提醒、审计导出

---

架构

本项目是 Agentic Query Layer (AQL) 模式的参考实现——它位于 AI Agent 与数据之间，提供基于权限、只读的自然语言访问能力，同时不向模型暴露底层数据。

User (plain English question)
    │
    ▼
AI Agent (Claude / GPT / Gemini / Ollama / local)
    │
    ▼  MCP Protocol
`moodle-mcp-server`  ← AQL connector for Moodle
    ├── Tool Registry (core + plugins)
    ├── Agent Runtime Config (core + plugin rules)
    ├── Optimized Data Layer (secure, efficient data handling)
    └── Moodle Client (REST API calls)
    │
    ▼
Moodle Web Services API

传输模式

• Stdio — dist/index.js — 以子进程方式运行，供 Claude Desktop 等客户端使用

开源核心有意仅提供 stdio。任何面向网络的封装、远程监管或高级插件接入，都应放在独立的商业节点 Agent 或封装器中。

插件文档

• 插件契约
• 创建插件
• Hello 插件示例

---

许可证

AGPL v3 — 请参阅 LICENSE。

这意味着你可以：

• ✅ 在任何环境中免费使用 moodle-mcp-server 核心
• ✅ 根据需要修改源代码
• ✅ 构建并分发衍生作品

你不能：

• ❌ 将 moodle-mcp-server 核心重新打包为闭源的竞争性商业产品
• ❌ 在不共享修改内容的情况下将其作为网络服务提供

商标声明

Moodle 是 Moodle Pty Ltd 的商标。moodle-mcp-server 是 CSMediaPro 的独立项目，与 Moodle Pty Ltd 或 Moodle 项目无关，也未获其认可、赞助或与其建立官方联系。使用该名称旨在说明它与 Moodle LMS 兼容。

---

由 CSMediaPro 构建

moodle-mcp-server 由 CSMediaPro 构建和维护。CSMediaPro 是一家专注于 AI 集成、系统工程和工作流自动化的软件开发公司。它是 Agentic Query Layer (AQL) 模式的首个参考实现。

• AQL 模式： https://csmediapro.com/notes/agentic-query-layer
• 联系邮箱： [email protected]