canvas-lms-mcp-server

提示

想让它在本地运行，只在你自己的电脑上使用？ 前往 💻 本地版 →。它提供相同的 209 个工具，无需 ngrok、无需密码，设置约需 5 分钟。

---

🤔 远程版还是本地版？

	🌐 远程版（本仓库）	💻 本地版
适用范围	任何支持远程服务的 MCP 客户端，可在任何设备上使用	此电脑上的桌面和命令行 MCP 客户端
运行时间	始终在后台运行	仅在 AI 应用打开时运行
所需条件	Node.js、Canvas 令牌、ngrok 账户和密码	Node.js 和 Canvas 令牌
网络暴露	公开 HTTPS 地址，受密码保护	无
多台电脑	✅ 自动故障转移（指南）	在每台电脑上单独安装

✨ 亮点

• 📊 成绩分析：what_if_grade、compute_needed_score、grade_impact_ranking，以及完整的加权明细
• 📅 规划：get_week_ahead、semester_snapshot、study_priority_ranking，一次调用即可查看所有课程的未完成作业
• 📝 提交作业：提交文本、URL 和文件，并可先预览而不实际提交
• 💬 讨论与收件箱：一次请求即可读取完整讨论串，还能给教师发消息
• 📁 内容：文件、页面、模块、讲座字幕，以及完整的 .imscc 课程导出
• 🔐 安全的远程访问：通过 ngrok 隧道使用密码保护的 OAuth 2.1
• 🔁 多计算机故障转移：在两台或更多计算机上运行；如果一台进入休眠，另一台会在大约一分钟内接管

🧭 工作原理

 Your AI app (web / desktop / mobile / CLI)
          │  HTTPS + OAuth
          ▼
   your-domain.ngrok-free.dev ──►  supervisor.js  ──►  index.js (127.0.0.1:3939/mcp)  ──►  Canvas API
                                   (keeps it alive,     (209 tools, OAuth,
                                    failover)            rate-limit aware)

🚀 快速开始

你需要： Node.js 18+、Canvas 账号和免费的 ngrok 账号。

1. 安装

使用 npm（最简单）：

npm install -g canvas-lms-mcp-remote
mkdir canvas-mcp
cd canvas-mcp
canvas-lms-mcp-remote init

该文件夹就是你的设置文件夹。其中保存了 .env、登录信息和日志，因此后续每个步骤都要在此文件夹中运行。

或者从源代码安装： git clone https://github.com/Fireiscoolsolo/canvas-lms-mcp-server.git，然后在该文件夹中运行 npm install。没有 git？可以改为从最新版本下载 zip 文件。此时，仓库文件夹就是你的设置文件夹。

所有命令

命令	功能
canvas-lms-mcp-remote init	在当前文件夹中创建 .env 模板
canvas-lms-mcp-remote	启动监督程序：服务、ngrok 隧道和故障转移
canvas-lms-mcp-remote serve	仅在 127.0.0.1 上启动 HTTP 服务（无隧道）
canvas-lms-mcp-remote --stdio	通过 stdin/stdout 提供服务，适用于会检查服务的目录

从源代码安装时，改用 node supervisor.js 和 node index.js。

2. 创建 Canvas 令牌

在 Canvas 中，前往 Account → Settings → Approved Integrations → + New Access Token。Canvas 只会显示一次令牌，请立即复制。

3. 设置 ngrok

winget install --id Ngrok.Ngrok -e
ngrok update                                   # the winget version is often too old (ERR_NGROK_121)
ngrok config add-authtoken <your-ngrok-authtoken>

然后在 ngrok 控制面板中申请免费的静态域名，例如 your-name.ngrok-free.dev。

4. 配置 .env

填写 init 创建的 .env。从源代码安装时，请先将 .env.example 复制为 .env。使用以下命令生成密码和密钥：

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

5. 测试

canvas-lms-mcp-remote

从源代码安装时，改为运行 node supervisor.js。 等待看到 active and serving at https://…，然后按 Ctrl+C。

6. 设置为登录时自动运行（Windows）

在 PowerShell 中，从你的设置文件夹（如果从源代码安装，则为仓库文件夹）运行：

$dir      = (Get-Location).Path
$action   = New-ScheduledTaskAction -Execute "$dir\run-supervisor.cmd" -WorkingDirectory $dir
$trigger  = New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\$env:USERNAME"
$settings = New-ScheduledTaskSettingsSet -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) -ExecutionTimeLimit ([TimeSpan]::Zero) -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -MultipleInstances IgnoreNew
Register-ScheduledTask -TaskName CanvasSupervisor -Action $action -Trigger $trigger -Settings $settings -Force
Start-ScheduledTask -TaskName CanvasSupervisor

通过 npm 安装？ 请改用此 $action 行：

$action = New-ScheduledTaskAction -Execute 'cmd.exe' -Argument '/c call "%APPDATA%\npm\canvas-lms-mcp-remote.cmd" >> supervisor.log 2>&1' -WorkingDirectory $dir

run-supervisor.cmd 假设 Node 位于 C:\Program Files\nodejs\node.exe。如果你的 Node 安装在其他位置，请编辑该文件。在 Linux 上，将其作为 systemd 用户服务运行（示例）。在 macOS 上，通过 launchd 或 pm2 运行 node supervisor.js。

7. 在每台设备上连接 AI 应用

在 AI 应用的设置中，添加一个自定义连接器（也称为远程 MCP 服务），URL 为 https://<your-domain>/mcp，然后使用密码登录。会将连接器同步到账号的应用也会在手机和桌面上显示该连接器。命令行和编辑器客户端可以使用相同的 URL，将其添加为 HTTP MCP 服务。

然后向你的助手提问：“运行 test_connection。”

🔁 多台计算机

你可以在两台或更多计算机上运行同一服务，例如台式机和笔记本电脑，这样即使一台计算机关机或进入休眠，服务也能保持在线。一台计算机提供服务；其他计算机则待命，并在需要时自动接管。

**➡️ 请按照多设备设置指南逐步操作。**指南涵盖安全复制设置、共享 ngrok 账号、计划任务、检查运行状态、测试故障转移、更新代码和更换密钥。

⚙️ 配置

所有设置均为 .env 中的环境变量。参见 .env.example。

变量	必填	默认值	描述
CANVAS_API_TOKEN	✅	—	你的 Canvas 个人访问令牌
CANVAS_BASE_URL	✅	—	例如：https://yourschool.instructure.com
CANVAS_MCP_PUBLIC_URL	✅	—	你的 ngrok 静态域名
CANVAS_MCP_PASSWORD	✅	—	OAuth 登录页面的密码
CANVAS_MCP_CLUSTER_SECRET	✅	—	用于保护计算机协调时使用的 /internal/* 端点的密钥
CANVAS_ALLOW_WRITES		true	false = 只读模式
CANVAS_PROFILE		full	core = 精选工具子集
CANVAS_CACHE_TTL		60	响应缓存时间，单位为秒
CANVAS_TIMEZONE		system	用于计算截止日期的 IANA 时区
CANVAS_DOWNLOAD_DIR		./canvas-downloads	下载工具保存文件的位置
CANVAS_MCP_HOST / _PORT		127.0.0.1 / 3939	绑定地址
CANVAS_MCP_OAUTH_STORE_PATH		./oauth-store.json	令牌存储路径
CANVAS_MCP_NGROK_PATH		winget path	ngrok.exe 的路径
CANVAS_MCP_TRANSPORT		http	stdio（或 --stdio 标志）通过 stdin/stdout 而非 HTTP 提供服务。供检查服务的目录使用。日常本地使用请参阅本地版

🧰 工具

分组	数量	亮点
身份	24	check_token_expiry、get_rate_limit_status、自定义数据存储
课程	16	权限、昵称、收藏
作业	12	list_missing_submissions、get_late_policy
提交	16	文本、URL 和文件提交，评论，评分标准评估
成绩	13	what_if_grade、compute_needed_score、grade_impact_ranking
测验	12	只读：日期、尝试记录、查看记录
讨论	17	get_full_topic_view、回复、评分
收件箱	14	消息、find_recipients、对话串
日历	11	活动、办公时间预约
内容	33	文件、页面、模块、字幕、.imscc 导出
小组	11	小组工作区
评分标准	11	同伴评审
搜索	3	smart_search，支持关键词回退
规划	11	get_week_ahead、semester_snapshot、study_priority_ranking
元数据	4	raw_canvas_request，可用于上方未列出的任何端点

🔐 安全

• 确认门控： 发送、提交、发布或删除内容的工具会先返回预览，只有在调用时传入 confirm: true 才会执行操作。
• 提示词注入防护： 他人撰写的文本会用 <<<CANVAS_CONTENT>>> 标记括起，并标注为不可信内容。
• 不参加测验： 刻意不包含测验作答端点。
• 仅限回环地址： 服务在 127.0.0.1 上监听。外部访问的唯一途径是隧道。
• OAuth 2.1： 每个 IP 每 15 分钟最多登录 10 次，访问令牌有效期为 1 小时，刷新令牌每次使用后都会更换。
• 独立的协调密钥： 计算机协调时使用的端点需要单独的共享密钥，并通过恒定时间比较进行验证。

切勿提交 .env、oauth-store.json 或 supervisor.log。这些文件已列入 .gitignore。参见 SECURITY.md。

🎓 负责任地使用

这是一个用于学习和组织安排的工具。它帮助你查看截止日期、了解成绩并规划一周安排。它绝不会代你参加测验；在你查看预览并确认之前，不会发送或提交任何内容。

• 遵守学校的学术诚信和可接受使用政策。有些学校会限制使用个人 API 令牌或第三方工具。
• 想彻底避免意外更改？将 CANVAS_ALLOW_WRITES=false 设为只读模式。

🛠️ 故障排除

症状	解决方法
ERR_NGROK_121	你的 ngrok 版本太旧。运行 ngrok update
ERR_NGROK_334 … already online	另一台电脑或残留的 ngrok.exe 占用了该域名。对于备用电脑来说，这是正常的
ERR_NGROK_3200（端点离线）	没有电脑在提供服务。检查 supervisor.log
登录时 ngrok 显示“You are about to visit…”页面	免费套餐中这是正常的。点击 Visit Site
startup probe failed	检查 CANVAS_BASE_URL 和你的网络连接
Canvas 返回 401	你的令牌已过期。创建一个新令牌
没有显示新工具	重新连接连接器，或重启你的 AI 应用

多台电脑相关的其他问题，请参阅多设备指南。

彻底重启。 仅运行 Stop-ScheduledTask 可能会留下仍在运行的进程：

Stop-ScheduledTask -TaskName CanvasSupervisor -ErrorAction SilentlyContinue
Get-CimInstance Win32_Process -Filter "Name='node.exe'" | Where-Object { $_.CommandLine -match 'supervisor\.js|index\.js' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }
Get-Process ngrok -ErrorAction SilentlyContinue | Stop-Process -Force
Start-ScheduledTask -TaskName CanvasSupervisor

已知限制： 学生令牌无法访问管理端点、成绩册历史记录、课程分析或测验统计信息。smart_search 是 Canvas 的 Beta 功能，通常会返回 404。

📄 许可证

MIT。本项目与 Instructure 无关。