使用说明

Canvas MCP服务器

此存储库包含一个模型上下文协议（MCP）服务器实现，用于与Canvas学习管理系统API交互。该服务器旨在与Claude Desktop和其他MCP兼容客户端配合使用。

备注：最近重构为模块化架构，以提高可维护性。遗留的单片实现已存档。

概述

Canvas MCP服务器弥合了Claude Desktop和Canvas学习管理系统之间的差距，提供 学生和教育工作者 他们的Canvas环境具有智能界面。基于模型上下文协议（MCP），它支持与Canvas数据的自然语言交互。

对于学生👨‍🎓

通过以下方式获得AI支持的帮助：

跟踪即将到来的任务和截止日期
监控所有课程的成绩
管理同行评审任务
访问课程内容和讨论
组织您的TODO列表

→ 作为一名学生开始

面向教育工作者👨‍🏫

通过以下方式加强您的教学：

作业和评分管理
学生分析和绩效跟踪
讨论和同行评审促进
符合FERPA标准 学生数据处理
批量消息和通信工具

→ 开始做一名教育工作者

🔒 隐私和数据保护

教育工作者：FERPA合规性

在处理学生数据时，通过系统的数据匿名化完成FERPA合规性：

源级数据匿名化 将真实姓名转换为一致的匿名ID（Student_xxxxxxxx）
自动电子邮件屏蔽 以及从讨论帖子和提交中过滤PII
仅本地处理 具有可配置的隐私控制(ENABLE_DATA_ANONYMIZATION=true)
符合FERPA的分析：在不暴露真实身份的情况下，问“哪些学生需要支持？”
去匿名化映射工具 让教师将匿名ID与本地真实学生相关联

所有学生数据都是匿名的之前它到达了人工智能系统。看教育者指南有关配置详细信息。

学生：您的数据保密

仅限您的数据：学生工具只能通过Canvas API的“self”端点访问您自己的Canvas数据
本地处理：所有内容都在您的机器上运行-没有数据发送到外部服务器
没有追踪：您的Canvas使用和AI交互保持私密
无需匿名：由于您只访问自己的数据，因此没有隐私问题

先决条件

Python 3.10+ -现代功能和类型提示所必需
Canvas API访问 -API令牌和机构URL
MCP客户端 -Claude Desktop（推荐）或其他MCP兼容客户端

支持的MCP客户端

Canvas MCP适用于支持模型上下文协议的任何应用程序。热门选项包括：

推荐：

克劳德桌面 -官方Anthropic桌面应用程序，完全支持MCP

AI编码助理：

泽德 -内置MCP支持的高性能代码编辑器
光标 -AI第一代码编辑器
Windsurf IDE （Codeium）-人工智能驱动的开发环境
继续 -开源AI代码助手

开发平台：

回复 -基于云的编码平台，集成MCP
源代码图科迪 -支持MCP的AI编码助手

企业：

微软复制品工作室 -企业环境中的MCP支持

看 MCP官方客户列表更多选择。

备注：虽然Canvas MCP旨在与任何MCP客户端配合使用，但本指南中的设置说明侧重于Claude Desktop。其他客户端的配置可能会有所不同。

安装

1.安装依赖项

# Install uv package manager (faster than pip)
pip install uv

# Install the package
uv pip install -e .

2.配置环境

# Copy environment template
cp env.template .env

# Edit with your Canvas credentials
# Required: CANVAS_API_TOKEN, CANVAS_API_URL

从以下位置获取Canvas API令牌： 画布→ 账户→ 设置→ 新访问令牌

学生须知：一些教育机构限制为学生创建API代币。如果您看到类似“您可以创建的访问令牌数量有限制”的错误或找不到令牌创建选项，请联系您所在机构的Canvas管理员或IT支持部门，请求API访问或协助创建令牌。

3.克劳德桌面设置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "canvas-api": {
      "command": "canvas-mcp-server"
    }
  }
}

验证

测试您的设置：

# Test Canvas API connection
canvas-mcp-server --test

# View configuration
canvas-mcp-server --config

# Start server (for manual testing)
canvas-mcp-server

可用工具

Canvas MCP服务器为与Canvas LMS API交互提供了一套全面的工具。这些工具被组织成逻辑类别，以提高可发现性和可维护性。

工具类别

学生工具 新

个人任务跟踪和截止日期管理
所有课程的成绩监控
TODO列表和同行评审管理
提交状态跟踪

共享工具 （学生和教育工作者）

课程工具 -列出和管理课程，获取详细信息，生成教学大纲内容摘要
讨论和公告工具 -管理讨论、公告和回复
页面和内容工具 -访问页面、模块和课程内容

教育工具 4. 作业工具 -通过分析处理作业、提交和同行评审 5. 评估工具 -用于量规的完整CRUD操作，包括验证、关联管理和评分 6. 用户和注册工具 -管理注册、用户和组 7. 分析工具 -查看学生分析、作业统计和进度跟踪 8. 消息传递工具 -向学生发送消息和公告

开发者工具 9. 发现工具 -使用搜索和探索可用的代码执行API操作 search_canvas_tools

📖 查看完整工具文档有关所有可用工具的详细信息。

🚀 代码执行API（新增！）

Canvas MCP现在支持 代码执行模式 以在执行批量操作时获得最大的令牌效率。

何时使用每种方法

传统工具调用 （用于简单查询）：

Ask Claude: "Show me my courses"
Ask Claude: "Get assignment details for assignment 123"

✅ 最适合：单查询、小数据集、快速查找

代码执行 （适用于批量操作）：

Ask Claude: "Grade all 90 Jupyter notebook submissions"
Ask Claude: "Send reminders to all students who haven't submitted"

✅ 最适合：批量处理、大型数据集、复杂分析

代币节省示例

场景：对90个Jupyter笔记本提交进行评分

方法	令牌使用	效率
传统	135万个令牌	将所有提交加载到上下文中
代码执行	3.5K代币	减少99.7%！ 🎉

示例：散装分级

import { bulkGrade } from './canvas/grading/bulkGrade';

await bulkGrade({
  courseIdentifier: "60366",
  assignmentId: "123",
  gradingFunction: (submission) => {
    // Analysis happens locally, not in Claude's context!
    const notebook = submission.attachments?.find(f =>
      f.filename.endsWith('.ipynb')
    );

    if (!notebook) return null; // Skip

    const hasErrors = analyzeNotebook(notebook.url);

    return hasErrors ? null : {
      points: 100,
      rubricAssessment: { "_8027": { points: 100 } },
      comment: "Great work! No errors."
    };
  }
});

发现可用工具

Canvas MCP服务器包括 search_canvas_tools MCP工具，帮助您发现和探索可用的代码执行API操作。此工具搜索TypeScript代码API文件，并返回有关可用Canvas操作的信息。

刀具参数：

query （字符串，可选）：按关键字过滤工具的搜索词（例如，“评分”、“作业”、“讨论”）。空字符串返回所有可用工具。
detail_level （string，可选）：控制返回多少信息。选项：
- "names"：仅文件路径（对于快速查找最有效）
- "signatures"：文件路径+函数签名+描述（推荐，默认）
- "full"：完整的文件内容（谨慎使用以进行详细检查）

示例用法：

用自然语言问克劳德：

“在代码API中搜索分级工具”
“有哪些批量操作可用？”
“显示所有代码API工具”

或直接通过MCP使用：

// Search for grading-related tools with signatures
search_canvas_tools("grading", "signatures")

// List all available tools (names only)
search_canvas_tools("", "names")

// Get full implementation details for bulk operations
search_canvas_tools("bulk", "full")

// Find discussion-related operations
search_canvas_tools("discussion", "signatures")

退货： JSON响应：

query：使用的搜索词
detail_level：要求的详细程度
count：找到的匹配工具数量
tools：一系列具有所需详细程度的匹配工具

代码API文件结构

src/canvas_mcp/code_api/
├── client.ts              # Base MCP client bridge
├── index.ts               # Main entry point
└── canvas/
    ├── assignments/       # Assignment operations
    │   └── listSubmissions.ts
    ├── grading/          # Grading operations
    │   ├── gradeWithRubric.ts
    │   └── bulkGrade.ts  # ⭐ Bulk grading (99.7% token savings!)
    ├── discussions/      # Discussion operations
    ├── courses/          # Course operations
    └── communications/   # Messaging operations

运作原理

发现：使用 search_canvas_tools 查找可用操作
执行：Claude读取TypeScript代码API文件并在本地执行它们
处理：数据保留在执行环境中（无上下文成本！）
结果：只有总结才能回到克劳德的背景

📖 查看批量分级示例以获取详细的演练。

与MCP客户端一起使用

此MCP服务器可与任何兼容MCP的客户端无缝协作：

自动启动：MCP客户端在需要时启动服务器
工具集成：画布工具出现在AI助手的界面中
自然语言：与以下提示自然交互：

学生：

“本周我有什么作业要交？”
“显示我当前的成绩”
“我需要完成哪些同行评审？”
“我已经提交了BADM 350的所有内容了吗？”

教育工作者：

“哪些学生没有提交最新的作业？”
“创建关于明天考试的公告”
“显示同行评审完成分析”

项目结构

遵循2025年最佳实践的现代Python包结构：

canvas-mcp/
├── pyproject.toml             # Modern Python project config
├── env.template              # Environment configuration template
├── src/
│   └── canvas_mcp/            # Main package
│       ├── __init__.py        # Package initialization
│       ├── server.py          # Main server entry point
│       ├── core/              # Core utilities
│       │   ├── config.py      # Configuration management
│       │   ├── client.py      # HTTP client
│       │   ├── cache.py       # Caching system
│       │   └── validation.py  # Input validation
│       ├── tools/             # MCP tool implementations
│       │   ├── courses.py     # Course management
│       │   ├── assignments.py # Assignment tools
│       │   ├── discussions.py # Discussion tools
│       │   ├── rubrics.py     # Rubric tools
│       │   ├── student_tools.py # Student-specific tools
│       │   ├── messaging.py   # Communication tools
│       │   ├── discovery.py   # Code API tool discovery (NEW!)
│       │   └── ...            # Other tool modules
│       ├── code_api/          # Code execution API (NEW!)
│       │   ├── client.ts      # MCP client bridge
│       │   └── canvas/        # Canvas operations
│       │       ├── grading/   # Bulk grading (99.7% token savings!)
│       │       ├── courses/   # Course operations
│       │       └── ...        # Other modules
│       └── resources/         # MCP resources
├── examples/                 # Usage examples (NEW!)
└── docs/                     # Documentation

文档

工具文档 -所有可用工具的完整参考
页面实施指南 -综合页面功能指南
课程文档模板 -高效课程文档的混合方法
开发指南 -架构细节和开发参考

技术细节

现代建筑（2025）

基于当前Python生态系统的最佳实践构建：

封装结构：现代 src/ 布局与 pyproject.toml
依赖管理：快速 uv 具有锁定依赖关系的包管理器
配置：基于环境的配置，带有验证和模板
入口点：通过以下方式使用正确的CLI命令 pyproject.toml 脚本
类型安全：完整的类型提示和运行时验证

核心组件

FastMCP框架：通过工具注册实现强大的MCP服务器
异步架构: httpx 具有连接池和速率限制的客户端
智能缓存：具有可配置TTL的智能请求缓存
配置系统：基于环境的配置，具有验证和默认值
教育重点：专为真实教学工作流程设计的工具

依赖项

现代Python包（参见 pyproject.toml):

fastmcp：MCP服务器框架
httpx：异步HTTP客户端
python-dotenv：环境配置
pydantic：数据验证和设置
python-dateutil：日期/时间处理

性能特点

连接池：重用HTTP连接以提高效率
请求缓存：最小化冗余Canvas API调用
异步操作：并发请求的非阻塞I/O
智能分页：Canvas API分页的自动处理
速率限制：尊重Canvas API限制和退让

开发工具

自动设置：一个命令安装脚本
配置测试：内置连接和配置测试
类型检查: mypy 支持类型安全
代码质量: ruff 和 black 用于格式化和换行

有关贡献者，请参阅开发指南详细的架构和开发参考。

故障排除

如果您遇到问题：

服务器无法启动 -验证您的配置设置： .env 文件、虚拟环境路径和依赖关系
身份验证错误 -检查Canvas API令牌的有效性和权限
连接问题 -验证Canvas API URL的正确性和网络访问
调试 -检查Claude Desktop控制台日志或手动运行服务器以获取错误输出

安全和隐私功能

API安全

您的Canvas API令牌授予对Canvas帐户的访问权限
永远不要承诺你的 .env 文件到版本控制
服务器在您的机器上本地运行，无需外部数据传输
如果可能的话，考虑使用权限有限的令牌

隐私控制（仅限教育工作者）

处理学生数据的教育工作者可以启用符合FERPA标准的匿名化：

# In your .env file
ENABLE_DATA_ANONYMIZATION=true  # Anonymizes student names/emails before AI processing
ANONYMIZATION_DEBUG=true        # Debug anonymization (optional)

学生不需要匿名，因为他们只访问自己的数据。

有关详细的隐私配置，请参阅：

教育者指南 -FERPA合规性和匿名化
学生指南 -学生隐私信息

发布到MCP注册表

此服务器已发布到模型上下文协议注册表便于安装。

自动发布（推荐）

发布是通过GitHub Actions自动完成的：

准备发布:

# Update version in pyproject.toml
# Update CHANGELOG if applicable
git commit -am "chore: bump version to X.Y.Z"
git push

创建并推送版本标签:
```
git tag vX.Y.Z
git push origin vX.Y.Z
```
自动化工作流程:
- 运行测试
- 构建Python包
- 发布到PyPI
- 使用GitHub OIDC发布到MCP注册表

出版的先决条件

PyPI帐户：在以下位置创建帐户 pypi.org
受信任的发布者设置 （推荐，不需要令牌）：
1. 访问 PyPI可信发布者
2. 为您的存储库添加“待定发布者”：
  - 所有者: vishalsachdev
  - 仓库: canvas-mcp
  - 工作流程: publish-mcp.yml
  - 环境：（留空）
3. 这将保留包名称并启用无标记发布

替代：使用API令牌（传统方法-不推荐）：

在PyPI生成令牌→ 帐户设置→ API令牌
添加为 PYPI_API_TOKEN 存储库设置中的机密
更新要使用的工作流 password: ${{ secrets.PYPI_API_TOKEN }}

手动出版（替代）

对于手动发布：

# Install MCP Publisher
curl -fsSL https://modelcontextprotocol.io/install.sh | sh

# Login using GitHub
mcp-publisher login github

# Publish server
mcp-publisher publish

注册表验证

这 server.json 在CI/CD期间，配置会根据MCP架构自动验证。要在本地验证：

# Download schema
curl -s https://registry.modelcontextprotocol.io/v0/server.schema.json -o /tmp/mcp-schema.json

# Validate (requires jsonschema CLI)
pip install jsonschema
jsonschema -i server.json /tmp/mcp-schema.json

贡献

欢迎投稿！请随意：

提交错误或功能请求的问题
通过改进创建拉取请求
分享您的用例和反馈

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

由...创建维沙尔·萨克德夫