moodle-mcp-server — 基于AI的LMS分析工具

向你的Moodle实例提问任何问题。几秒钟内获得结构化答案。

moodle-mcp-server 是一个开源的MCP（模型上下文协议）服务器，它将AI代理直接连接到Moodle的网络服务API。它是CSMediaPro更广泛的代理查询层（AQL）工作背后的Moodle连接器。

无需学习报表生成器、编写SQL或导出CSV，你只需用自然语言提问——AI代理会查询你的LMS并返回结构化数据。

项目主页： https://csmediapro.com/products/moodle-mcp-server npm包： https://www.npmjs.com/package/moodle-mcp-server-aql MCP注册表： io.github.csmediapro/moodle-mcp-server-aql

功能特性

• 核心查询工具 — 课程目录、用户注册、作业、分类导航、站点元数据、用户查找和缓存管理

• 高级报告插件 — 可选工具，如课程完成报告和近期活动，可通过插件运行时附加

• LLM无关性 — 适用于Claude、GPT、Gemini、Ollama或任何兼容MCP的AI客户端

• 零LMS修改 — 使用Moodle现有的网络服务API，无需安装插件

• 合规就绪的数据处理 — 安全、高效的数据处理，设计上注重隐私

• 只读 — 从不修改Moodle数据，适用于生产环境

• 插件可扩展 — 将新的工具模块放入目录；工具和可选的代理路由提示会在运行时自动注册

Related MCP server: Moodle MCP Server

快速开始

前提条件

• Node.js 20+

• 一个启用了网络服务的Moodle实例

• 一个Moodle API令牌（站点管理 → 插件 → 网络服务 → 管理令牌）

与MCP客户端一起使用

大多数用户通过MCP客户端（如Claude Desktop）启动服务器：

{
  "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 中。

user-directory 插件会存储一个规范化的完整用户缓存，其中自定义个人资料 字段被扁平化为顶级键，例如 school。一旦该缓存存在， list_users 可以在内存中过滤缓存的用户，而 summarize_user_directory_field 可以返回缓存的不同值和计数。例如，“显示独特的学校”或 “显示学校以及分配给每所学校的学生数量”会汇总缓存的 school 字段，而无需再次获取Moodle数据。

配置身份

核心拥有两个不同的服务器身份字段：

• 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实例，并呈现一个聊天界面，你可以在其中用自然语言提问。

连接LLM

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。

推荐的本地模型

选项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）

高级插件（单独提供）

• 高级报告 — 成绩册、跨课程比较、自定义报表生成器

• 用户分析 — 进度跟踪、参与度评分、风险标记

• 用户目录 — 缓存目录列表，支持标准和自定义个人资料字段的结构化过滤

• 合规包 — 认证跟踪、过期提醒、审计导出

架构

User (plain English question)
    │
    ▼
AI Agent (Claude / GPT / Gemini / Ollama / local)
    │
    ▼  MCP Protocol
`moodle-mcp-server`
    ├── 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及类似客户端使用

OSS核心有意仅提供 stdio。任何面向网络的包装器、远程监督或高级插件附件都属于单独的商用节点代理或包装器。

插件文档

• 插件合约

• 创建插件

• 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 构建和维护，这是一家专注于AI集成、系统工程和工作流自动化的软件开发公司。

• 联系方式： contact@csmediapro.com