内容
# 画布学习管理系统 MCP 服务器
[](https://www.npmjs.com/package/@charlie.act7/canvas-mcp-server)
[](https://www.npmjs.com/package/@charlie.act7/canvas-mcp-server)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](./LICENSE)
**画布学习管理系统** 的模型上下文协议（MCP）服务器。它作为一个桥梁，允许 AI 助手（例如 Claude Code、Claude Desktop、Cursor、Windsurf、Cline、Roo Code、GitHub Copilot、Continue、Zed、Codex CLI、n8n、OpenAI 自定义 GPT 等）通过自然语言查询、评分、审计和管理画布课程、作业、评分标准、提交、测验、对话和分析。目前支持两种传输方式：`stdio`（默认）和具有交互式 Swagger API 文档的 Streamable-HTTP。
> **西班牙语版本：** [README.es.md](README.es.md) | **LLM 集成指南：** [llms-install.md](llms-install.md)
---
- [要求和平台支持](#要求和平台支持)
- [工作原理](#工作原理)
- [安装](#安装)
- [连接到 Claude Code](#连接到-claude-code)
- [连接到其他客户端](#连接到其他客户端)
- [Claude Desktop](#claude-desktop)
- [Cursor](#cursor)
- [Windsurf (Codeium)](#windsurf-codeium)
- [Cline & Roo Code](#cline--roo-code)
- [GitHub Copilot](#github-copilot)
- [Continue.dev](#continuedev)
- [Zed 编辑器](#zed-editor)
- [Codex CLI](#codex-cli)
- [通用 MCP 客户端（stdio）](#通用-mcp-客户端stdio)
- [HTTP 服务器和 OpenAI 自定义 GPT](#http-服务器和-openai-自定义-gpt)
- [身份验证和凭证](#身份验证和凭证)
- [传输](#传输)
- [用例和提示](#用例和提示)
- [工具](#工具)
- [资源](#资源)
- [配置参考](#配置参考)
- [开发](#开发)
- [文档](#文档)
- [许可证](#许可证)
---
## 要求和平台支持
- **Node.js** ≥ 18.0.0（推荐 Node.js ≥ 20.x）。
- **画布学习管理系统访问**：您所在机构的画布学习管理系统的有效账户（例如 `myschool.instructure.com`）。
- **画布 API 访问令牌**：通过您的画布账户设置页面生成。
- **Linux / macOS / Windows / WSL2**。
---
## 工作原理
当您与服务器交互时，通信流程如下：
```mermaid
graph LR
User([用户]) -->|自然语言指令| AI["AI 助手（例如 Claude）"]
AI -->|MCP 请求| MCP["画布 MCP 服务器"]
MCP -->|REST API - HTTPS| Canvas["画布学习管理系统"]
Canvas -->|响应| MCP
MCP -->|处理数据| AI
AI -->|友好答案| User
```
1. **您询问 AI** （例如，*"创建下周五截止的作业"*）。
2. **AI 检测您的意图** 并与 **画布 MCP 服务器** 通信，发送所需的参数。
3. **服务器向官方画布学习管理系统 API 发送安全调用**，使用 HTTPS。
4. **画布学习管理系统处理操作** 并返回响应负载。
5. **AI 向您确认操作成功**，使用自然语言。
---
## 安装
### 已发布软件包
```bash
npx @charlie.act7/canvas-mcp-server@latest
```
这是最终用户的推荐路径。`npx` 会缓存二进制文件，并在 `@latest` 上自我更新。
### 交互式 CLI 设置
在运行之前，交互式配置您的画布凭证：
```bash
npx @charlie.act7/canvas-mcp-server config
```
### 从源代码
```bash
git clone https://github.com/CharlieCardenasToledo/mcp-canvas-server.git
cd mcp-canvas-server
npm install
npm run build
node dist/index.js
```
---
## 连接到 Claude Code
CLI 形式：
```bash
claude mcp add canvas \
--env CANVAS_API_TOKEN=您的访问令牌 \
--env CANVAS_API_DOMAIN=myschool.instructure.com \
-- npx -y @charlie.act7/canvas-mcp-server@latest
```
或从本地构建：
```bash
claude mcp add canvas \
--env CANVAS_API_TOKEN=您的访问令牌 \
--env CANVAS_API_DOMAIN=myschool.instructure.com \
-- node /绝对路径/到/mcp-canvas-server/dist/index.js
```
手动形式 — 放入 `~/.claude.json`：
```json
{
"mcpServers": {
"canvas": {
"command": "npx",
"args": ["-y", "@charlie.act7/canvas-mcp-server@latest"],
"env": {
"CANVAS_API_TOKEN": "您的访问令牌",
"CANVAS_API_DOMAIN": "myschool.instructure.com"
}
}
}
}
```
---
## 连接到其他客户端
有关所有 AI 客户端（Windsurf、Cline、Roo Code、Copilot、Continue、Zed、LibreChat、自定义 GPT）的逐步设置指南，请参阅 [`llms-install.md`](llms-install.md)。
### Claude Desktop
编辑您的 Claude Desktop 配置文件：
- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"canvas": {
"command": "npx",
"args": ["-y", "@charlie.act7/canvas-mcp-server@latest"],
"env": {
"CANVAS_API_TOKEN": "您的访问令牌",
"CANVAS_API_DOMAIN": "myschool.instructure.com"
}
}
}
}
```
### Cursor — `~/.cursor/mcp.json`
```json
{
"mcpServers": {
"canvas": {
"command": "npx",
"args": ["-y", "@charlie.act7/canvas-mcp-server@latest"],
"env": {
"CANVAS_API_TOKEN": "您的访问令牌",
"CANVAS_API_DOMAIN": "myschool.instructure.com"
}
}
}
}
```
### Codex CLI
```bash
codex mcp add canvas \
--env CANVAS_API_TOKEN=您的访问令牌 \
--env CANVAS_API_DOMAIN=myschool.instructure.com \
npx -y @charlie.act7/canvas-mcp-server@latest
```
### 通用 MCP 客户端（stdio）
任何可以启动 stdio 上 MCP 服务器的客户端都可以使用 `npx -y @charlie.act7/canvas-mcp-server@latest`。服务器支持 MCP 2025（`tools`、`resources`、`prompts`）。
### HTTP 服务器和 OpenAI 自定义 GPT
使用 Fastify 和交互式 Swagger 文档以 HTTP 模式运行服务器：
```bash
npx @charlie.act7/canvas-mcp-server serve-http --port 3000 --host 0.0.0.0
# 或从源代码：
npm run start:http
```
访问 `http://localhost:3000` 以检查交互式 Swagger / OpenAPI 定义或连接到 OpenAI 自定义 GPT 操作。
---
## 身份验证和凭证
### 步骤 1：获取画布凭证
1. 登录到您的 **画布学习管理系统** 账户。
2. 进入 **账户** > **设置** 在侧边栏导航中。
3. 滚动到 **批准的集成** 并点击 **+ 新建访问令牌**。
4. 输入目的（例如 "Claude 画布 MCP"）并点击 **生成令牌**。
5. 立即复制生成的令牌并安全存储（它不会再次显示）。
> [!IMPORTANT]
> 记录您的 **画布域名**。这是您所在机构的画布平台的网络地址，例如：`myschool.instructure.com`。
### 令牌自动续期
如果您的机构强制令牌过期，服务器会在每次请求前检查活动令牌的过期时间，并在令牌过期前 24 小时内自动再生和持久化。
切换和调整：
- `CANVAS_TOKEN_AUTO_RENEW=false` — 禁用自动令牌再生。
- `CANVAS_TOKEN_RENEW_THRESHOLD_HOURS=48` — 更改续期阈值窗口（默认：`24` 小时）。
---
## 传输
服务器支持两种传输模式：
### stdio（默认）
```bash
npx @charlie.act7/canvas-mcp-server@latest
```
由桌面应用程序和 CLI 工具（Claude Desktop、Claude Code、Cursor、Codex）使用。
### HTTP 服务器 / Fastify REST API
```bash
npx @charlie.act7/canvas-mcp-server serve-http --port 3000 --host 0.0.0.0
```
可选传递 `--port <port>`（默认 `3000`）和 `--host <host>`（默认 `0.0.0.0` 或 `127.0.0.1`）。
---
## 用例和提示
> [!TIP]
> **节省令牌和效率：** 尽可能在您的提示中指定画布 ID 或直接画布 URL（例如，`https://[您的机构].instructure.com/courses/[课程 ID]/assignments/[作业 ID]`）。这可以防止 AI 扫描您的所有课程/资源，从而导致更快的响应和大量的令牌节省。
### 课程审计和查询
- *"本学期我有哪些活跃的课程？检查是否有多个活跃的章节/平行课程。*"
- *"显示 'Essay 1: Introduction to Sociology' 在 Sociology 101 中所有未评分的提交。*"
- *"谁在化学课的 Student Group A 中？*"
- *"作业 'Project Proposal' 是否有相关的评分标准？如果有，请检索其标准。*"
- *"在我的生物学课程中搜索与 '光合作用' 相关的所有内容 — 作业、页面和讨论。*"
### 创建和组织课程内容
- *"在我的课程中创建一个名为 '第 1 周：基础知识' 的新模块。*"
- *"在 '第 1 周' 模块中添加一个子标题 '必读材料'，并链接到课程大纲页面。*"
- *"在我的商业课程中，创建一个名为 '案例研究 1：市场分析' 的作业。添加一个包含标准、要求和分数的指令表。*"
- *"在我的课程中创建一个主题讨论话题，标题为 '每周反思'，并将其固定在顶部。*"
### 评分和缺席管理
- *"对于作业 '案例研究 1'，查找所有未提交作业的学生。给他们分配 0 分，并添加评论：'活动未提交。'*"
- *"根据评分标准给约翰的 'Essay 1' 提交作业打 90 分，并添加反馈。*"
### 学生参与度和分析
- *"显示我的微积分课程的活动分析 — 本周学生们有多活跃？*"
- *"哪些学生最近几天在课程 12345 中没有活动？*"
### 消息和通信
- *"向学生 [ID] 发送私人消息，提醒他们 '项目提案' 明天到期。*"
- *"我的画布收件箱中有多少未读消息？*"
---
## 工具
画布 MCP 服务器公开了 **117 个工具**，分为 21 个功能类别：
| 类别 | 工具 | 描述 |
|---|---|---|
| **课程** | `list_courses` · `create_course` · `update_course` · `get_syllabus` | 管理和配置课程 |
| **模块** | `list_modules` · `create_module` · `update_module` · `delete_module` · `create_module_item` · `update_module_item` · `delete_module_item` | 模块及其项目的完整 CRUD |
| **页面** | `list_pages` · `get_page_content` · `create_page` · `update_page` · `delete_page` | Wiki 页面发布和编辑 |
| **文件和文件夹** | `list_files` · `upload_file` · `update_file` · `delete_file` · `list_folders` · `create_folder` · `update_folder` · `delete_folder` | 文件管理，支持文件夹 |
| **作业** | `get_assignments` · `get_assignment` · `create_assignment` · `update_assignment` · `delete_assignment` · `update_assignment_dates` · `bulk_update_due_dates` · `list_assignment_groups` | 作业生命周期完整 |
| **提交** | `get_submissions` · `get_submission` · `get_submission_comments` · `delete_submission_comment` · `submit_assignment` | 查看和管理学生提交 |
| **评分** | `grade_submission` · `grade_multiple_submissions` · `audit_course` | 单独或批量评分 |
| **评分标准** | `list_rubrics` · `get_rubric` · `create_rubric` · `update_rubric` · `create_rubric_association` | 构建和附加评分标准 |
| **经典测验** | `list_quizzes` · `get_quiz` · `create_quiz` · `update_quiz` · `update_quiz_dates` · `list_quiz_questions` · `get_quiz_question` · `create_quiz_question` · `update_quiz_question` · `delete_quiz_question` · `create_quiz_group` | 经典画布测验引擎 |
| **新测验（LTI）** | `create_new_quiz` · `update_new_quiz` · `delete_new_quiz` · `list_new_quiz_items` · `get_new_quiz_item` · `create_new_quiz_item` · `update_new_quiz_item` · `delete_new_quiz_item` | 现代 LTI 测验引擎（`/api/quiz/v1`） |
| **学生** | `list_students` · `list_students_with_grades` · `get_student_grades` · `get_student_assignments` · `list_assignment_due_dates` | 学生名单和进度跟踪 |
| **注册** | `list_course_enrollments` · `enroll_user` · `remove_enrollment` · `get_user` · `get_profile` · `search_users` | 管理课程中的人员 |
| **分组** | `list_group_categories` · `create_group_category` · `list_groups_in_category` · `create_group` · `assign_unassigned_members` · `add_group_member` | 学生分组管理 |
| **讨论** | `list_discussions` · `get_discussion_entries` · `create_discussion` · `delete_discussion` · `post_discussion_reply` | 讨论板 |
| **公告** | `list_announcements` · `post_announcement` · `update_announcement` | 课程公告 |
| **对话** | `list_conversations` · `get_conversation` · `get_conversation_unread_count` · `send_conversation` · `reply_to_conversation` | 私人 inbox 消息 |
| **日历** | `list_appointment_groups` · `get_appointment_group` · `create_appointment_group` · `update_appointment_group` · `delete_appointment_group` · `list_appointment_group_users` · `list_appointment_group_groups` · `get_next_appointment` | 调度和约会 |
| **分析** | `get_course_analytics` · `get_student_analytics` · `get_course_activity_stream` · `search_course_content` | 参与度数据和内容搜索 |
| **同行评审** | `list_peer_reviews` · `get_submission_peer_reviews` · `create_peer_review` · `delete_peer_review` | 配置和管理同行评估 |
| **访问令牌** | `list_access_tokens` · `get_access_token` · `create_access_token` · `update_access_token` · `regenerate_access_token` · `delete_access_token` | 管理画布 API 令牌，自动续期 |
| **健康和配置** | `health_check` · `set_canvas_config` | 连接检查和运行时配置更新 |
---
## 资源
支持的原生 MCP 资源：
| 资源 URI | 描述 |
|---|---|
| `canvas://courses/{id}/readme` | 格式化 Markdown 课程摘要 |
| `canvas://courses/{id}/pages/{slug}` | 画布页面的直接 HTML 内容 |
---
## 配置参考
所有配置参数都可以通过环境变量传递或通过 CLI 配置存储（`npx @charlie.act7/canvas-mcp-server config`）。
| 环境变量 | 默认值 | 目的 |
|---|---|---|
| `CANVAS_API_TOKEN` | _(未设置)_ | 画布学习管理系统 API 访问令牌。 |
| `CANVAS_API_DOMAIN` | _(未设置)_ | 您的画布学习管理系统实例的域名（例如 `myschool.instructure.com`）。 |
| `CANVAS_TOKEN_AUTO_RENEW` | `true` | 自动续期即将到期的访问令牌。 |
| `CANVAS_TOKEN_RENEW_THRESHOLD_HOURS` | `24` | 令牌过期前触发自动续期的阈值（默认：`24` 小时）。 |
| `PORT` / `HTTP_PORT` | `3000` | 运行 `serve-http` 时的 HTTP 端口。 |
| `HTTP_HOST` | `0.0.0.0` | HTTP 服务器模式下的主机接口绑定。 |
| `GEMINI_API_KEY` | _(未设置)_ | (可选) 本地 LLM 桥接/脚本实用程序的 Gemini API 密钥。 |
| `OLLAMA_HOST` | `http://localhost:11434` | (可选) 本地 Ollama 主机地址，用于本地模型桥接。 |
---
## 开发
```bash
npm run build # 编译 TypeScript 源代码（tsc）
npm run dev # 监视模式编译（tsc --watch）
npm start # 在 stdio 模式下运行 MCP 服务器
npm run start:http # 在 http://localhost:3000 上运行 HTTP 服务器，带有 Swagger UI
npm run chat # 启动交互式 Ollama 桥接测试 CLI
```
### 源代码布局
- `src/index.ts` — CLI 入口点（Commander），stdio MCP 服务器引导程序
- `src/http-server.ts` — Fastify HTTP 服务器，Swagger / OpenAPI 路线定义
- `src/common/` — `canvas-client.ts`（API 客户端和令牌自动续期），`config.ts`（`conf` 管理器），`types.ts`
- `src/tools/` — 117+ 工具实现，按功能模块划分
- `src/resources/` — MCP 资源提供者（`canvas://`）
- `src/prompts/` — MCP 提示模板
---
## 文档
- [`README.es.md`](./README.es.md) — Español 版的 README。
- [`llms-install.md`](./llms-install.md) — 主 AI 客户端和编辑器集成指南。
---
## 许可证
该项目在 **MIT 许可证**下获得许可。由 [Charlie Cárdenas Toledo](https://github.com/CharlieCardenasToledo) 创建。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器