项目介绍
Canvas MCP 服务器
<!--mcp-name: io.github.vishalsachdev/canvas-mcp-->
此仓库包含一个用于与 Canvas 学习管理系统 API 交互的 Model Context Protocol (MCP) 服务器实现。该服务器设计用于与 Claude Desktop 和其他 MCP 兼容客户端配合使用。
注意：最近重构为模块化架构以提高可维护性。旧的单体实现已归档。
概述
Canvas MCP 服务器在 Claude Desktop 和 Canvas 学习管理系统之间架起了一座桥梁，为学生和教师提供了一个智能界面，以便与他们的 Canvas 环境进行交互。基于 Model Context Protocol (MCP)，它实现了与 Canvas 数据的自然语言交互。
🎉 最新发布：v1.0.4
发布日期：2025年11月10日 | 查看完整发行说明
主要特性
- 🚀 代码执行环境 - 执行自定义 TypeScript 代码以进行高效的批量操作（节省 99.7% 的令牌）
- 📊 新的 MCP 工具：
bulk_grade_submissions- 带有可选评分标准评估的高效批量评分bulk_grade_discussions- 节省令牌的讨论评分 APIsearch_canvas_tools- 动态发现可用的 MCP 工具
改进
- MCP 2.10 兼容性 - 更新 FastMCP 至 >=2.10.0
- 结构化日志 - 标准化的错误处理和日志记录
- 灵活的评分 - 简单评分场景中评分标准评估可选
- GitHub Actions 集成 - 自动化工作流和聊天会话导出
- 增强的验证 - 更好的错误处理和验证反馈
最近的 Bug 修复
- 修复了
get_assignment_details工具中的描述截断问题（现在返回完整的 HTML 描述）
对于学生 👨🎓
获取 AI 助手的帮助：
- 跟踪即将到期的作业和截止日期
- 监控你在所有课程中的成绩
- 管理同伴评审任务
- 访问课程内容和讨论
- 组织你的待办事项列表
对于教师 👨🏫
通过以下方式提升教学效果：
- 作业和评分管理
- 学生分析和绩效跟踪
- 讨论和同伴评审促进
- FERPA 合规的学生数据处理
- 批量消息和通信工具
🔒 隐私与数据保护
对于教师：FERPA 合规
通过系统性的数据匿名化实现完全的 FERPA 合规：
- 源级数据匿名化 将真实姓名转换为一致的匿名 ID（Student_xxxxxxxx）
- 自动电子邮件屏蔽 和 PII 过滤从讨论帖子和提交中移除
- 本地处理 配置隐私控制（
ENABLE_DATA_ANONYMIZATION=true） - FERPA 合规分析：询问“哪些学生需要支持？”而不会暴露真实身份
- 去匿名化映射工具 供教职员工本地关联匿名 ID 与真实学生
所有学生数据在到达 AI 系统之前都会被匿名化。有关配置详情，请参阅 教师指南。
对于学生：您的数据保持私密
- 仅访问您的数据：学生工具仅通过 Canvas API 的“self”端点访问您自己的 Canvas 数据
- 本地处理：所有操作都在您的机器上运行 - 不会将数据发送到外部服务器
- 无跟踪：您的 Canvas 使用情况和 AI 交互保持私密
- 无需匿名化：由于您只访问自己的数据，因此没有隐私问题
前提条件
- Python 3.10+ - 必须用于现代特性和类型提示
- Canvas API 访问 - API 令牌和机构 URL
- MCP 客户端 - Claude Desktop（推荐）或其他 MCP 兼容客户端
支持的 MCP 客户端
Canvas MCP 可与任何支持 Model Context Protocol 的应用程序配合使用。流行的选项包括：
推荐：
- Claude Desktop - 官方 Anthropic 桌面应用，全面支持 MCP
AI 编码助手：
- Zed - 高性能代码编辑器，内置 MCP 支持
- Cursor - AI 首选的代码编辑器
- Windsurf IDE（由 Codeium 提供） - AI 驱动的开发环境
- Continue - 开源 AI 代码助手
开发平台：
- Replit - 基于云的编码平台，支持 MCP 集成
- Sourcegraph Cody - 支持 MCP 的 AI 编码助手
企业：
- Microsoft Copilot Studio - 企业环境中的 MCP 支持
更多选项请参阅 官方 MCP 客户端列表。
注意：虽然 Canvas MCP 设计为与任何 MCP 客户端兼容，但本指南中的设置说明主要针对 Claude Desktop。其他客户端的配置可能有所不同。
安装
1. 安装依赖项
# 安装 uv 包管理器（比 pip 更快）
pip install uv
# 安装包
uv pip install -e .
2. 配置环境
# 复制环境模板
cp env.template .env
# 编辑您的 Canvas 凭证
# 必需：CANVAS_API_TOKEN, CANVAS_API_URL
从 Canvas → 账户 → 设置 → 新建访问令牌 获取您的 Canvas API 令牌
学生注意事项：某些教育机构限制学生创建 API 令牌。如果您看到类似“您创建的访问令牌数量有限”或找不到创建令牌的选项，请联系您的机构 Canvas 管理员或 IT 支持部门请求 API 访问权限或帮助创建令牌。
3. Claude Desktop 设置
添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：
{
"mcpServers": {
"canvas-api": {
"command": "canvas-mcp-server"
}
}
}
验证
测试您的设置：
# 测试 Canvas API 连接
canvas-mcp-server --test
# 查看配置
canvas-mcp-server --config
# 启动服务器（手动测试用）
canvas-mcp-server
可用工具
Canvas MCP 服务器提供了一整套与 Canvas LMS API 交互的工具。这些工具按逻辑分类，以便更好地发现和维护。
工具类别
学生工具（新！）
- 个人作业跟踪和截止日期管理
- 跨所有课程的成绩监控
- 待办事项列表和同伴评审管理
- 提交状态跟踪
共享工具（学生和教师）
- 课程工具 - 列出和管理课程，获取详细信息，生成包含课程大纲的摘要
- 讨论和公告工具 - 管理讨论、公告和回复
- 页面和内容工具 - 访问页面、模块和课程内容
教师工具
4. 作业工具 - 处理作业、提交和同伴评审，带有分析
5. 评分标准工具 - 评分标准的完整 CRUD 操作，包括验证、关联管理和评分（包括 bulk_grade_submissions 用于高效的批量评分）
6. 用户和注册工具 - 管理注册、用户和组
7. 分析工具 - 查看学生分析、作业统计和进度跟踪
8. 消息工具 - 发送消息和公告给学生
开发者工具
9. 发现工具 - 搜索和探索可用的代码执行 API 操作，使用 search_canvas_tools 和 list_code_api_modules
10. 代码执行工具 - 执行 TypeScript 代码，使用 execute_typescript 进行高效的批量操作（节省 99.7% 的令牌！）
🚀 代码执行 API（新！）
Canvas MCP 现在支持 代码执行模式，以在执行批量操作时实现最大的令牌效率。
何时使用每种方法
传统工具调用（适用于简单查询）：
询问 Claude: “显示我的课程”
询问 Claude: “获取作业 123 的详细信息”
✅ 适用于：单个查询、小数据集、快速查找
批量评分工具（适用于带有预定义评分的批量评分）：
询问 Claude: “根据特定的评分标准为这 10 名学生评分”
✅ 适用于：当您已经拥有评分/分数时的批量评分，同时进行并发处理
代码执行（适用于带有自定义逻辑的批量操作）：
询问 Claude: “通过分析每个笔记本对所有 90 个 Jupyter 笔记本提交进行评分”
询问 Claude: “向尚未提交的学生发送提醒”
✅ 适用于：带有自定义分析逻辑的批量处理，大数据集，复杂条件
令牌节省示例
场景：对 90 个 Jupyter 笔记本提交进行评分
| 方法 | 令牌使用 | 效率 |
|---|---|---|
| 传统 | 1.35M 令牌 | 加载所有提交到上下文 |
| 代码执行 | 3.5K 令牌 | 99.7% 减少！ 🎉 |
示例：批量评分
import { bulkGrade } from './canvas/grading/bulkGrade';
await bulkGrade({
courseIdentifier: "60366",
assignmentId: "123",
gradingFunction: (submission) => {
// 分析在本地进行，不在 Claude 的上下文中！
const notebook = submission.attachments?.find(f =>
f.filename.endsWith('.ipynb')
);
if (!notebook) return null; // 跳过
const hasErrors = analyzeNotebook(notebook.url);
return hasErrors ? null : {
points: 100,
rubricAssessment: { "_8027": { points: 100 } },
comment: "做得很好！没有错误。"
};
}
});
示例：批量讨论评分
对带有初始帖子和同伴评审要求的讨论帖子进行评分：
import { bulkGradeDiscussion } from './canvas/discussions/bulkGradeDiscussion';
// 首先预览评分（干运行）
await bulkGradeDiscussion({
courseIdentifier: "60365",
topicId: "990001",
criteria: {
initialPostPoints: 10, // 初始帖子的分数
peerReviewPointsEach: 5, // 每次同伴评审的分数
requiredPeerReviews: 2, // 必须评审 2 位同伴
maxPeerReviewPoints: 10 // 评审分数上限 10 分
},
dryRun: true // 首先预览
});
// 然后应用评分
await bulkGradeDiscussion({
courseIdentifier: "60365",
topicId: "990001",
assignmentId: "1234567", // 应用评分所需
criteria: {
initialPostPoints: 10,
peerReviewPointsEach: 5,
requiredPeerReviews: 2,
maxPeerReviewPoints: 10
},
dryRun: false
});
特性：
- 自动分析初始帖子与同伴评审
- 可配置的评分标准和分数分配
- 可选的延迟处罚和自定义截止日期
- 干运行模式以预览评分后再应用
- 并发处理并带有速率限制
- 返回全面的参与度分析
发现可用工具
Canvas MCP 服务器包含一个 search_canvas_tools MCP 工具，帮助您发现和探索可用的代码执行 API 操作。此工具搜索 TypeScript 代码 API 文件并返回有关可用 Canvas 操作的信息。
工具参数：
query（字符串，可选）：用于过滤工具的关键字搜索词（例如，“评分”，“作业”，“讨论”）。空字符串返回所有可用工具。detail_level（字符串，可选）：控制返回多少信息。选项："names"：仅文件路径（最适用于快速查找）"signatures"：文件路径 + 函数签名 + 描述（推荐，默认）"full"：完整文件内容（谨慎使用，适用于详细检查）
示例用法：
用自然语言询问 Claude：
- “在代码 API 中搜索评分工具”
- “有哪些批量操作可用？”
- “显示所有代码 API 工具”
或直接通过 MCP 使用：
// 搜索与评分相关的工具及其签名
search_canvas_tools("评分", "signatures")
// 列出所有可用工具（仅名称）
search_canvas_tools("", "names")
// 获取批量操作的完整实现细节
search_canvas_tools("批量", "full")
// 查找与讨论相关的操作
search_canvas_tools("讨论", "signatures")
返回： JSON 响应，包含：
query：使用的搜索词detail_level：请求的详细级别count：找到的匹配工具数量tools：包含请求详细级别的匹配工具数组
代码 API 文件结构
src/canvas_mcp/code_api/
├── client.ts # 基础 MCP 客户端桥接
├── index.ts # 主入口点
└── canvas/
├── assignments/ # 作业操作
│ └── listSubmissions.ts
├── grading/ # 评分操作
│ ├── gradeWithRubric.ts
│ └── bulkGrade.ts # ⭐ 批量评分（节省 99.7% 的令牌！）
├── discussions/ # 讨论操作
│ ├── listDiscussions.ts
│ ├── postEntry.ts
│ └── bulkGradeDiscussion.ts # ⭐ 批量讨论评分
├── courses/ # 课程操作
└── communications/ # 消息操作
工作原理
- 发现：使用
search_canvas_tools查找可用操作 - 执行：Claude 读取 TypeScript 代码 API 文件并在本地执行
- 处理：数据保留在执行环境中（不消耗上下文成本！）
- 结果：只有摘要返回到 Claude 的上下文
📖 查看批量评分示例 以获得详细的逐步指导。
与 MCP 客户端的使用
此 MCP 服务器可以无缝与任何 MCP 兼容客户端配合使用：
- 自动启动：MCP 客户端在需要时启动服务器
- 工具集成：Canvas 工具出现在您的 AI 助手界面中
- 自然语言：通过自然语言与提示进行交互，例如：
学生：
- “我这周有哪些作业到期？”
- “显示我的当前成绩”
- “我需要完成哪些同伴评审？”
- “我是否已提交 BADM 350 的所有内容？”
教师：
- “哪些学生尚未提交最新作业？”
- “创建关于明天考试的公告”
- “显示同伴评审完成分析”
快速入门示例
初次使用 Canvas MCP？请查看这些实用指南：
项目结构
遵循 2025 年最佳实践的现代 Python 包结构：
canvas-mcp/
├── pyproject.toml # 现代 Python 项目配置
├── env.template # 环境配置模板
├── src/
│ └── canvas_mcp/ # 主包
│ ├── __init__.py # 包初始化
│ ├── server.py # 主服务器入口点
│ ├── core/ # 核心工具
│ │ ├── config.py # 配置管理
│ │ ├── client.py # HTTP 客户端
│ │ ├── cache.py # 缓存系统
│ │ └── validation.py # 输入验证
│ ├── tools/ # MCP 工具实现
│ │ ├── courses.py # 课程管理
│ │ ├── assignments.py # 作业工具
│ │ ├── discussions.py # 讨论工具
│ │