canvas-student-mcp

即使学校禁用 API 令牌也能正常使用的 Canvas LMS MCP 服务器。

为 Claude（或任何 MCP 客户端）提供对 Canvas 账户的只读实时访问：课程、教学大纲、含提交状态的作业、成绩、公告、模块、页面、文件、讨论、测验、待办事项和日历。配合 Notion 连接器使用，一个提示即可归档整个课程。

为什么还需要另一个 Canvas MCP？

已有几个不错的 Canvas MCP 服务器——vishalsachdev/canvas-mcp、DMontgomery40/mcp-canvas-lms、mtgibbs/canvas-lms-mcp 等。它们都需要个人 API 令牌。

问题在于：许多大学禁用了学生的自助令牌生成功能。打开 账户 → 设置，根本没有 + 新建访问令牌 按钮。在这些学校，所有基于令牌的服务器都是死路一条。

本服务器通过 会话 Cookie 认证 解决了这个问题：在浏览器中登录 Canvas，复制一次会话 Cookie，即可连接。Canvas Web UI 正是通过这个 Cookie 与同一个 /api/v1 REST API 通信，因此没有任何管理策略能在不破坏 Canvas 本身的情况下阻止它。

这需要在底层实现（而基于令牌的服务器不需要）：

• XSSI 防护剥离——Cookie 认证的 Canvas 响应前缀为 while(1);，这会破坏朴素的 JSON 解析

• 登录重定向检测——过期的会话会重定向到登录页面，而不是返回 401；服务器会捕获重定向和非 JSON 响应体，并准确告知如何刷新，而不是返回令人费解的错误

• 带凭证的文件下载——令牌会话会获得一个 verifier= 参数，使文件 URL 可自认证；Cookie 会话则没有，因此下载必须携带会话 Cookie（否则 Canvas 返回 500）。重定向会被手动跟踪，确保凭证永远不会被转发到 CDN

• 过期感知错误——每种故障模式都会在错误信息中说明修复方法

除了认证之外，其他设计原则也使其与众不同：

• 设计上只读。 每个工具都是 GET 请求。服务器物理上无法提交作业、发布讨论或修改任何内容——可安全地交给自主代理使用。

• 上下文高效的响应。 Canvas API 的负载非常庞大；每个工具都会裁剪到 LLM 实际需要的字段，将 HTML 转换为纯文本（保留链接 URL），并限制分页并附上明确的截断提示。

• 小巧且可审计。 严格的 TypeScript，三个运行时依赖（MCP SDK、zod 和用于 PDF 文本的 unpdf）。在信任它访问学校账户之前，你可以通读全部代码。

如果你的学校允许，令牌认证仍然受支持——Cookie 是备选方案，而非唯一途径。

Related MCP server: canvas-parent-mcp

工具（29 个）

其中三个值得特别说明。

canvas_read_file 将课程材料转换为可读文本，这使得“就本周的幻灯片考考我”或“迟交作业政策是什么”等功能真正可用。PDF 通过 unpdf 处理；Office 格式在仓库内处理——.docx、.pptx 和 .xlsx 是 XML 的 ZIP 容器，因此通过 Node 内置的 zlib 实现一个小型 ZIP 读取器即可处理所有三种格式，无需额外依赖。canvas_read_syllabus 在此基础上构建：它会检测教学大纲是否仅为文件链接，并读取附件内容，这是常见情况（在测试的 3 门课程中占 2 门）。canvas_grade_breakdown 实现了 Canvas 的两种评分模型（按分组加权和总分制），将其计算结果与 Canvas 报告的成绩进行交叉验证，并在存在弃分规则或未发布的作业分组导致预测不可靠时明确告知——而不是默默地返回一个自信但错误的数字。canvas_get_conversation 传递了 auto_mark_as_read=false，因此代理读取你的收件箱时不会静默地将消息标记为已读；该行为已通过一个真实的未读讨论串验证，而非仅仅假设。

请参阅 ROADMAP.md 了解下一步计划以及为何写入操作被明确排除在范围之外。

快速开始

无需安装——npx 会按需获取：

npx canvas-student-mcp

或者从源码运行：

git clone https://github.com/xmike04/canvas-student-mcp.git
cd canvas-student-mcp
npm install && npm run build

获取凭据

选项 A——API 令牌（如果你的学校允许）：Canvas → 账户 → 设置 → 已批准的集成 → + 新建访问令牌。

选项 B——会话 Cookie（适用于受限学校）：

1. 在任何浏览器中登录你学校的 Canvas

2. 开发者工具（Cmd/Ctrl+Shift+I）→ 网络 标签页 → 刷新

3. 点击任何指向你 Canvas 域的请求 → 请求头 → 复制完整的 cookie: 值 （或仅复制 canvas_session=... 这一对——这一个 Cookie 就足够了）

任一凭据均可授予对你 Canvas 账户的读取权限。请像对待密码一样对待它。

存储凭据（macOS：使用钥匙串）

MCP 客户端配置是纯文本 JSON。在 macOS 上，你可以将凭据完全排除在配置之外：

security add-generic-password -s canvas-student-mcp -a cookie -w 'canvas_session=PASTE_VALUE_HERE' -U

使用 -a token 代替 -a cookie 以使用 API 令牌。服务器会先检查环境变量，再检查钥匙串，因此这是可选加入的，跳过也不会出问题。CANVAS_NO_KEYCHAIN=1 可禁用钥匙串查找。

注册到 Claude

Claude Code——凭据存储在钥匙串中，配置完全不包含任何秘密：

claude mcp add canvas --scope user \
  --env CANVAS_BASE_URL=https://yourschool.instructure.com \
  -- npx -y canvas-student-mcp

直接传递凭据而不使用钥匙串：

claude mcp add canvas --scope user \
  --env 'CANVAS_COOKIE=canvas_session=PASTE_VALUE_HERE' \
  --env CANVAS_BASE_URL=https://yourschool.instructure.com \
  -- npx -y canvas-student-mcp

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "canvas": {
      "command": "node",
      "args": ["/absolute/path/to/canvas-student-mcp/dist/index.js"],
      "env": {
        "CANVAS_COOKIE": "canvas_session=PASTE_VALUE_HERE",
        "CANVAS_BASE_URL": "https://yourschool.instructure.com"
      }
    }
  }
}

使用 CANVAS_API_TOKEN 代替 CANVAS_COOKIE 进行令牌认证（如果两者都设置，令牌优先）。验证方式：“检查我的 Canvas 个人资料。”

当 Cookie 过期时（你的浏览器会话结束），每个工具都会明确告知——重新复制并更新配置即可。如果勾选了“保持登录状态”，会话通常可持续数周。

代理技能

三个打包的工作流位于 skills/。将其中任何一个复制到 ~/.claude/skills/（或你项目的 .claude/skills/），Claude 将在请求匹配时自动使用：

cp -R skills/canvas-morning-check ~/.claude/skills/

连接后可尝试的指令

• “未来两周内所有课程有哪些作业要交？”

• “我每门课的当前成绩是多少，哪些作业还没交？”

• “总结本周所有课程的公告。”

• “导出我的 BIOL 1710 课程并归档到我的 Notion 学校文件夹中。”（配合 Notion 连接器）

• “读取我历史课第三周的页面，并就内容考考我。”

架构说明

• stdio 传输，无状态——每个客户端会话一个进程，无端口、无遥测、无存储。数据流向为 Canvas → 本进程 → 你的 MCP 客户端，不会流向其他地方。

• 自动分页——跟踪 Canvas 的 Link: rel="next" 标头，限制为 5 页 × 100 项，并附有明确的截断提示，以确保代理上下文保持可控。

• HTML 转文本——用于教学大纲、描述、公告和页面——结构标签转换为换行符/项目符号，链接转换为 文本 (url)。

• 每个工具都有 Zod 输入模式；全程声明了 MCP 注解（readOnlyHint）。

开发

npm run build   # strict TypeScript compile
npm test        # smoke test: MCP handshake, all 30 tools register, error paths

冒烟测试完全离线运行 —— CI 不需要 Canvas 账户，并且它会设置 CANVAS_NO_KEYCHAIN=1，这样真实的存储凭据就不会泄露到测试运行中。

发布

发布从 CI（.github/workflows/release.yml）运行，因此没有人在笔记本电脑上发布：

npm version minor && git push --follow-tags

推送标签会触发构建、完整的测试套件、包内容检查以及标签与 package.json 匹配的守卫 —— 然后通过来源证明进行发布，该证明将发布的 tarball 与构建它的提交和工作流程以加密方式关联起来。从“操作”选项卡手动运行工作流程会执行除发布之外的所有操作，作为试运行。

安全模型

• 只读：每个 Canvas 调用都是 GET；没有工具可以写入 Canvas。即使收件箱也会保持消息未读状态。

• 凭据存在于 MCP 客户端的环境配置或 macOS 钥匙串中 —— 永远不会存储在此仓库的磁盘上，也永远不会传输到学校 Canvas 域之外的任何地方。文件下载会手动跟踪重定向，因此凭据永远不会转发到 CDN。

• 随时轮换：登出 Canvas（或撤销令牌），凭据将在所有地方失效。

• canvas_auth_status 会告诉你正在使用哪个凭据、存储位置以及是否仍然有效。

许可证

MIT