内容
# Moodle 多课程服务端（增强版）
[](https://www.npmjs.com/package/@ernesto-butto/moodle-mcp-server)
[](https://modelcontextprotocol.io/)
[](https://nodejs.org/)
[](https://opensource.org/licenses/MIT)
一个增强的 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务端，使 AI 助手（如 Claude）能够与 Moodle LMS 交互。**此分支版本添加了多课程支持**，允许您从单个 MCP 服务端管理多个课程。
> 🍴 这是 [peancor/moodle-mcp-server](https://github.com/peancor/moodle-mcp-server) 的增强分支版本，具有重大改进。
> ✅ **已在 Moodle 4.5 上测试通过**（构建版本：20241007）。Moodle 4.x 内置的“Moodle 移动网络服务”包含了此服务端所需的所有 API 函数 - 不需要自定义服务。
> 📖 **教师或 Moodle 管理员？** 您不需要此页面上的任何内容。请遵循 [设置指南](SETUP_GUIDE.md) 以获取简单的逐步说明（英文和西班牙文）。
## ✨ 此分支版本的新功能
| 功能 | 原始版本 | 此分支版本 |
|---------|----------|-----------|
| 多课程支持 | ❌ 仅支持单个课程 | ✅ 动态 `courseId` 参数 |
| 列出所有课程 | ❌ 不可用 | ✅ `list_courses` 工具 |
| 查看课程内容 | ❌ 不可用 | ✅ `get_course_contents` 工具 |
| 管理员/教师访问 | ❌ 仅限基于注册的访问 | ✅ 支持基于权限的访问 |
| 论坛交互 | ❌ 不可用 | ✅ 浏览、发布和回复论坛帖子 |
## 🛠️ 可用工具
### 课程发现
| 工具 | 描述 |
|------|-------------|
| `list_courses` | 列出您有权访问的所有课程，包含 ID、名称和摘要 |
| `get_course_contents` | 获取课程章节、模块和活动（课程结构） |
### 学生管理
| 工具 | 描述 |
|------|-------------|
| `get_students` | 检索已注册的学生，包含 ID、名称、电子邮件和最后访问时间 |
### 作业管理
| 工具 | 描述 |
|------|-------------|
| `get_assignments` | 列出所有作业，包含截止日期和最大成绩 |
| `get_submissions` | 查看学生的作业提交情况 |
| `get_submission_content` | 获取详细的作业提交内容，包含文件 |
| `provide_feedback` | 评分作业并提供反馈 |
### 测试管理
| 工具 | 描述 |
|------|-------------|
| `get_quizzes` | 列出课程中的所有测试 |
| `get_quiz_grade` | 获取学生特定测试的成绩 |
### 论坛管理
| 工具 | 描述 |
|------|-------------|
| `get_forums` | 列出课程中的所有论坛 |
| `get_forum_discussions` | 列出讨论，包含作者、回复数和帖子 ID |
| `create_forum_discussion` | 在论坛中创建新的讨论线程（HTML 格式） |
| `reply_to_forum_discussion` | 回复现有的论坛帖子（HTML 格式） |
### 多课程支持
所有特定于课程的工具都接受可选的 `courseId` 参数：
```
"列出我所有的 Moodle 课程" → list_courses()
"列出课程 5 中的学生" → get_students(courseId=5)
"显示作业" → get_assignments() // 如果已配置，则使用默认值
"课程 10 中的测试" → get_quizzes(courseId=10)
```
**工作原理：**
- 如果您在请求中指定 `courseId`，则使用该课程
- 如果您未指定 `courseId`，则使用 `MOODLE_COURSE_ID` 的默认值（如果已配置）
- `MOODLE_COURSE_ID` 是**可选的** - 您可以完全省略它，并始终动态指定课程
## 📋 要求
- **Node.js** v18 或更高版本
- **Moodle API 令牌**，具有适当的权限
- **Moodle** 实例，已启用网络服务
## 🚀 安装
无需安装 - Claude Desktop 和 Claude Code 直接通过 `npx` 从 npm 运行服务端。
### 对于 Claude Desktop（Windows/macOS）
编辑您的配置文件：
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"moodle": {
"command": "npx",
"args": ["-y", "@ernesto-butto/moodle-mcp-server"],
"env": {
"MOODLE_API_URL": "https://your-moodle.com/webservice/rest/server.php",
"MOODLE_API_TOKEN": "your_token_here",
"MOODLE_COURSE_ID": "4"
}
}
}
}
```
> 💡 **提示：** 如果您更喜欢始终动态指定课程，可以完全省略 `MOODLE_COURSE_ID`。
### 对于 Claude Code（Linux/WSL）
添加到您的项目的 `.mcp.json`：
```json
{
"mcpServers": {
"moodle": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@ernesto-butto/moodle-mcp-server"],
"env": {
"MOODLE_API_URL": "https://your-moodle.com/webservice/rest/server.php",
"MOODLE_API_TOKEN": "${MOODLE_API_TOKEN}",
"MOODLE_COURSE_ID": "4"
}
}
}
}
```
然后将您的令牌设置为环境变量：
```bash
echo 'export MOODLE_API_TOKEN="your_token_here"' >> ~/.bashrc
source ~/.bashrc
```
### 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `MOODLE_API_URL` | ✅ 是 | 您的 Moodle 网络服务端点 |
| `MOODLE_API_TOKEN` | ✅ 是 | 身份验证的 API 令牌 |
| `MOODLE_COURSE_ID` | ❌ 否 | 默认课程 ID（可选 - 使用 `list_courses` 动态发现课程） |
### 从源代码（用于开发）
```bash
git clone https://github.com/ernesto-butto/moodle-mcp-server.git
cd moodle-mcp-server
npm install
npm run build
```
## 🔑 获取 Moodle API 令牌
1. 以管理员身份登录 Moodle
2. 进入 **站点管理 → 服务器 → 网络服务 → 外部服务**
3. 确保 **“Moodle 移动网络服务”** 已启用（它包含所有必需的 API 函数）
4. 进入 **站点管理 → 服务器 → 网络服务 → 管理令牌**
5. 点击 **创建令牌**，选择教师的用户帐户和 **“Moodle 移动网络服务”**
6. 复制令牌
> 💡 **就是这样。** 在 Moodle 4.x 中，移动网络服务已经涵盖了此服务端使用的所有功能。不需要创建自定义服务或添加个别函数。
### 查找您的课程 ID
只需询问 Claude：*“列出我所有的 Moodle 课程”* - `list_courses` 工具将返回所有课程及其 ID。
您也可以在访问课程时在 URL 中找到它：`https://your-moodle.com/course/view.php?id=4` - ID 是 `4`。
<details>
<summary><strong>高级：自定义服务（用于最小权限）</strong></summary>
如果您的管理员更喜欢创建具有所需功能的自定义服务而不是使用移动网络服务，请添加以下功能：
- `core_course_get_courses`
- `core_course_get_contents`
- `core_enrol_get_enrolled_users`
- `mod_assign_get_assignments`
- `mod_assign_get_submissions`
- `mod_assign_get_grades`
- `mod_assign_get_submission_status`
- `mod_assign_save_grade`
- `mod_quiz_get_quizzes_by_courses`
- `mod_quiz_get_user_best_grade`
- `mod_forum_get_forums_by_courses`
- `mod_forum_get_forum_discussions`
- `mod_forum_add_discussion`
- `mod_forum_add_discussion_post`
</details>
## 💡 示例用法
配置完成后，您可以询问 Claude：
- *“列出我所有的 Moodle 课程”*
- *“显示课程 5 中的学生”*
- *“单元 3 中有哪些作业？”*
- *“获取课程 10 的课程内容”*
- *“显示测验 15 中学生 42 的成绩”*
- *“列出课程 5 中的论坛”*
- *“显示论坛 3 中的讨论”*
- *“在论坛 3 中创建一个新的讨论，主题为‘第 5 周反馈’”*
- *“回复帖子 10，附上我对学生作品的评论”*
## 🧪 开发
### 监视模式（自动重建）
```bash
npm run watch
```
### 使用 MCP 检视器进行调试
```bash
npm run inspector
```
这将打开一个基于浏览器的调试界面。
### 测试
**单元测试** - 使用模拟的 Moodle API 响应运行完整的 Vitest 套件（不需要凭证）：
```bash
npm test
```
**MCP 集成测试** - 通过 stdio（与 Claude Desktop 相同的路径）使用 MCP 协议启动服务端，并验证工具注册、参数验证和可选的实时 API 调用：
```bash
# 仅限模式 + 验证（不需要凭证）
npm run build && node test-mcp.mjs
# 对实时 Moodle 实例进行测试
MOODLE_API_URL="https://your-moodle.com/webservice/rest/server.php" \
MOODLE_API_TOKEN="your-token" \
MOODLE_COURSE_ID="4" \
node test-mcp.mjs
```
集成测试检查：
1. 所有工具均使用正确的名称和必需的参数注册
2. 参数验证为缺少的字段抛出正确的错误
3. （使用凭证）读取工具从实时 Moodle 实例返回数据
## 🤝 贡献
欢迎贡献！请随时提交拉取请求。
## 📄 许可证
[MIT](LICENSE) - 基于 [peancor](https://github.com/peancor/moodle-mcp-server) 的工作
## 🙏 致谢
- [peancor](https://github.com/peancor/moodle-mcp-server) 的原始 MCP 服务端
- Anthropic 的 [模型上下文协议](https://modelcontextprotocol.io/)
- [Moodle](https://moodle.org/) LMS 社区
