Brightspace Mcp Server

Brightspace MCP 服务

作者：Rohan Muppa，普渡大学电子与计算机工程系

让 AI 查看你在 Brightspace 上的课程，你只需问：

“这周有哪些截止任务？”·“我所有课程都及格了吗？”·“总结今天的公告”·“把我的讲义幻灯片转换成抽认卡”

可与 Claude Desktop、Claude Code、Cursor、ChatGPT Desktop、Windsurf，以及其他支持 MCP（将工具接入 AI 的标准方式）的应用配合使用。它只会读取你的课程，绝不会提交、编辑或删除任何内容。

3 步开始使用

1. 如果还没有安装，请先安装 Node.js（版本 22 或更高）。下载、运行安装程序即可。

2. 打开终端并运行设置命令：

   npx -y brightspace-mcp-server@latest setup
   

   它会询问你学校的 Brightspace 地址、用户名和密码，以及登录时如何确认身份（通过手机应用，或短信等其他方式）。密码会保存在电脑自带的密码存储中（Mac 上的 Keychain、Windows 上的 Credential Manager），绝不会写入文件。在登录前，它会自动连接你安装的 Claude Desktop、Cursor、Antigravity、Codex 或 Claude Code。如果其中某个应用已有指向其他位置的 brightspace 条目（例如旧的本地构建或分支），设置程序会显示该条目，并在替换前征求你的同意。

   在 Mac 上：当 Keychain 询问是否允许 node 使用保存的 Brightspace 密码时，请选择始终允许，不要只选“允许”。这样之后登录时（运行 auth 命令或向 AI 应用提问）就能读取密码，而不会再次询问。

3. 重启 AI 应用并向它提问——第一个问题会触发登录。如果手机要求你批准登录，请批准后再提问一次。

如果你就读于以下学校之一，可添加对应标志，跳过输入地址：--purdue、--suny、--western、--tudelft、--cuny、--leiden、--mcgill、--ngeeann、--javeriana。

**想让 AI 帮你安装？**将以下内容粘贴到 Claude Code、Cursor、Windsurf、Copilot 或 Codex 中：

Install brightspace-mcp-server for me by following
https://github.com/RohanMuppa/brightspace-mcp-server/blob/main/LLMs.md
(use --purdue at Purdue, --suny at SUNY, --tudelft at TU Delft, --cuny at CUNY, --leiden at Leiden, --mcgill at McGill, --ngeeann at Ngee Ann Polytechnic, or --javeriana at Javeriana Cali).

AI 会尽可能自行完成所有操作：检查你的电脑、下载登录时使用的浏览器，并连接你的 AI 应用。然后，它会提供一条需要你在终端中运行的命令。这条命令会询问你的密码，并等待你在手机上批准登录。这是唯一需要你亲自操作的部分。之后，AI 会检查能否查看你的课程。

使用其他 AI 应用？将命令 npx -y brightspace-mcp-server@latest 添加到其 MCP 设置中（Windows 上使用：cmd /c npx -y brightspace-mcp-server@latest）。各应用的具体步骤见：docs/troubleshooting.md。

我的学校支持吗？

如果你的学校使用 D2L Brightspace，支持。以下学校已内置自动登录：

学校	登录方式	标志
Purdue	Microsoft（手机批准、验证器代码或浏览器）	--purdue
SUNY	共享网站，可选择校区	--suny
Western University	Microsoft	--western
TU Delft	NetID（无需双重验证）	--tudelft
CUNY	CUNY Login，每次都需要验证器代码	--cuny
Leiden University	SURFconext → Microsoft	--leiden
McGill University	Microsoft Entra	--mcgill
Javeriana Cali	OneGate（密码 + 验证器代码）	--javeriana
Ngee Ann Polytechnic	Microsoft Entra	--ngeeann
其他任何 D2L 学校	粘贴你的 Brightspace 地址。如果无法识别登录页面，请在设置中的登录问题处选择选项 2，以打开页面并手动完成登录	无

各学校的特殊情况：docs/sign-in.md。

可询问的内容

关于	示例
成绩	“我所有课程都及格了吗？” · “比较一下我各门课程的成绩” · “教授对 Mini-Assignment 1 有什么评价？”（学生自己的作业反馈会从 Brightspace 为学生提供的所有入口读取）· “我的期中考试有反馈吗？”（通过测验评分的成绩会链接到测验，因为测验反馈（包括只能在 LockDown Browser 中查看的反馈）无法通过 API 读取）
截止日期	“未来 48 小时内有哪些截止事项？” · “帮我安排本周的学习计划”
作业和评分标准	“实验 4 的具体要求是什么？” · “我为什么在分析这一项被扣分了？” · “我提交 HW 3 了吗？”（如果 Brightspace 不向学生提供自己的提交列表，则会改查作业的反馈页面；如果两处都没有显示提交记录，则会报告为未知，而不会说成未提交）
测验和考试	“本周有哪些测验会关闭？” · “成绩册里有没有不在作业列表中的期中考试？”（测验会从测验列表、课程内容和成绩册中收集，因此即使测验已关闭或列表遗漏了测验，仍会显示；每门课程都会说明其测验来源是否全部成功响应，如果 Brightspace 拒绝了某个来源，则会标记为不完整，而不会假称已全部查全；“完整”表示每个来源都已响应，并不保证列出了所有测验。如果成绩册列关联到列表遗漏的测验，现在只要能读取该测验，就会显示为包含日期和尝试次数的测验，而不是只有成绩的空白行。现在，在仅发送成绩列文档所述 GradeType 的租户中，也会显示仅存在于成绩册中的行。隐藏的成绩列、隐藏的作业和未启用的测验不会产生此类行。每门课程中超过前 30 个的课程内容测验只会从课程内容中列出，并且课程会标记为不完整。测验行还可能注明测验是开放、已关闭还是尚未开放，也可能标记 Brightspace 未能返回详细信息的测验；对于未列出的测验，每门课程最多查询 20 个成绩册条目，如果无法识别课程的测验工具，则最多查询 5 个）
公告	“今天有教授发布重要内容吗？” · “阅读今天公告中附带的文件”
课程内容	“查找期中复习幻灯片” · “下载模块 5 中的所有 PDF” · “在本课程中搜索答疑时间” · 或者直接在线阅读文件，不必保存
教学大纲	“ECE 264 教学大纲中的迟交政策是什么？”（如果课程将教学大纲放在 Simple Syllabus 等外部工具中，则会提供链接供你打开）
人员	“ECE 264 的助教有哪些？” · “我的项目小组里有哪些人？”
讨论	“总结最终项目讨论帖中的最新发言”
讲座视频	“教授在周二的录制视频中是怎么讲 pinch-off 的？”（支持 Kaltura（包括 BoilerCast LTI 链接）和 YouTube。如果 YouTube 要求登录或进行“非机器人”验证，回答会说明这一点，并提供视频链接以及自行获取文字稿的方法：在浏览器中打开链接，选择“显示文字稿”，然后粘贴文字稿。服务无法替你通过该验证）
日历	“我的期中考试是什么时候？” · “周四的实验课取消了吗？”
面向教师和助教	“哪些学生还没提交实验 4？” · “我给这名学生的作业留了什么反馈？” · “下载这名学生提交的 PDF”（学生会看到明确提示，说明这些操作需要“教师访问权限”；但学生可以查看自己已发布的反馈，见下文）
退出登录	“让我退出 Brightspace”（你的 AI 应用可能会先要求你确认；详情请参阅要求你登录时）

提示词

带有提示词选择器的应用（如 Claude Desktop）还提供了四个现成的提示词，你只需点击一下即可开始，而不必输入问题：

提示词	参数	提问内容
weekly_briefing	—	汇总所有课程过去 7 天内的待办事项、新内容以及成绩变化
grade_audit	courseId（可选）	分析一门或所有课程的成绩，并标出缺失或分数较低的项目
study_planner	daysAhead（可选，默认值为 7）	根据即将到期的截止日期和日历事件规划学习时间
course_summary	courseId（必填）	提供一门课程的教学大纲、内容提纲、作业和成绩

你可能需要的设置

以下设置均为可选项，可在 AI 应用的 MCP env 配置或 shell 中设置。完整列表见 LLMs.md。

设置	作用
D2L_REMEMBER_MFA=true	勾选 Microsoft 的“不要再次询问”选项，使之后的登录跳过第二重验证（默认关闭；不适用于公用电脑）。setup 会在唯一的“你希望多久批准一次登录”问题中将其作为选项 2 提问，并保存为 config.json 中的 rememberMfa；环境变量会覆盖该设置（详情）
D2L_TOTP_SECRET	身份验证器设置密钥，这样 Microsoft Entra 的“输入代码”验证就会在这台电脑上完成，而不是在手机上完成（默认关闭）。建议使用 setup（选项 3），它会将密钥保存在操作系统钥匙串中；此变量适用于没有钥匙串的 CI 和容器，但安全性较低，因为任何能够读取进程环境的程序都能获取你的第二重验证凭据（详情）
D2L_HEADLESS=false	登录期间显示浏览器窗口，供需要点击操作的 MFA 方式使用
D2L_DUO_PASSCODE=1	使用 Duo 时，输入一次性密码，而不是等待推送通知
D2L_SESSION_COOKIE / D2L_ACCESS_TOKEN	粘贴 Cookie 或令牌，以完全跳过浏览器（操作方法）
D2L_INCLUDE_COURSES / D2L_EXCLUDE_COURSES	按课程 ID 限制 AI 可见的课程
D2L_ACTIVE_ONLY=false	包含已结束注册的课程
D2L_CURRENT_ONLY=true	仅显示当前注册时段内的课程，例如 Brightspace 的“当前课程”小组件
D2L_NO_UPDATE_CHECK=1	关闭新版本通知
D2L_RUNTIME_IDLE_SECONDS	共享后台服务在没有问题运行时等待多久后停止（默认值为 600）
D2L_DEV_MODE=true	写入不含内容的本地日志，记录工具调用和登录事件，以便排查会话问题（操作方法）

所有聊天共用一个服务

所有聊天已经共用一个 Brightspace 服务，无需进行任何设置。每个聊天仍会启动常规命令，但该命令现在只是一个轻量中继：任意聊天提出的第一个问题都会在这台电脑上启动一个共享后台服务，其他所有聊天（Claude Desktop、Codex、Cursor、……）都会使用同一个服务。这意味着所有聊天只需登录一次，共用一个已保存的会话和一个缓存。即使两个聊天同时启动，最终也只会有一个服务。关闭一个聊天不会中断另一个聊天的问题。连续 10 分钟没有问题运行后，共享服务会自动停止，下一个问题会重新启动它。

只有使用相同设置和相同版本软件包的聊天才会共用一个服务。使用不同 D2L_* 设置启动的聊天，或在软件包更新后启动的聊天，都会获得各自的服务。由于后台服务不会附属于任何聊天，其日志会写入 ~/.d2l-session/…/shared-runtime/ 下的 runtime.log。设置 D2L_RUNTIME_IDLE_SECONDS 可更改服务停止前的等待时长。

自行运行共享服务（可选）

你也可以自行运行一个副本，并通过 URL 让每个聊天都连接到它。它会像之前一样使用已保存的密码、会话和登录状态；需要登录的问题仍只需登录一次，供所有聊天使用。

1. 生成一个密钥令牌，只需一次。 聊天必须提供该令牌，这样其他程序和网页就无法读取你的成绩。生成一个：

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

   将其保存为名为 D2L_HTTP_TOKEN 的用户环境变量，并确保服务和 Codex 都能读取它。在 Windows 上：依次选择“开始”→“编辑你的帐户的环境变量”→“新建”，将令牌粘贴为变量值（之后打开的应用和终端都能读取它）。在 macOS 或 Linux 上：将 export D2L_HTTP_TOKEN=<token> 添加到 shell 配置文件（~/.zshrc、~/.bashrc）；从 Dock 或桌面菜单启动的 Codex 应用可能无法读取该配置文件，因此请从终端启动它。服务不会打印令牌。
2. 启动服务，并让它在单独的终端中持续运行：

   npx -y brightspace-mcp-server@latest http
   

   这需要支持 HTTP 的发行版本；若要先从源代码检出版本试用，请运行 npm run build，然后运行 node build/index.js http。它会在 http://127.0.0.1:18765/mcp 上监听，仅限本机访问。使用 --port 18766 或 D2L_HTTP_PORT 选择其他端口，并在第 3 步的 URL 中使用同一端口。每次登录后启动一次即可：聊天不会启动服务；同一端口上运行的第二个副本会立即因“already in use”而停止，不会与第一个副本同时运行。服务启动时不会登录。
3. 将 Codex 指向该服务。 在 ~/.codex/config.toml 中，将 [mcp_servers.brightspace] 条目里的 command 和 args 行替换为：

   [mcp_servers.brightspace]
   url = "http://127.0.0.1:18765/mcp"
   bearer_token_env_var = "D2L_HTTP_TOKEN"
   

   （如果该变量的值为 Bearer <token>，也可以使用 env_http_headers = { "Authorization" = "D2L_HTTP_AUTHORIZATION" }。）项目自己的 .codex/config.toml 会覆盖此配置，因此请移除其中的任何 brightspace 条目，或将其改为相同配置。重新运行 setup 会识别此条目并保留它，包括令牌设置。
4. 重启 Codex。 已打开的聊天会继续使用原来的每聊天服务，直到 Codex 重启。如果停止或重启共享服务，调用会失败，直到服务恢复；如果之后仍然失败，请新建聊天或重启 Codex。

变化如下：

• 设置应配置在服务上，而不是 Codex 中。 URL 条目没有进程可用于传入 env 表，因此应在运行 http 的终端中、在启动服务的目录下的 .env 文件中，或通过 setup 保存 上表中的 D2L_* 设置。
• 登录消息会显示在服务的终端中。 需要批准的号码仍会显示在聊天的回答中；对于会显示工具进度的客户端，该号码也会在问题运行期间显示。
• **停止服务：**按 Ctrl+C。正在运行的问题会先完成；再次按 Ctrl+C 可立即停止。
• **更新服务：**重启服务，而不是 Codex。重启客户端只会让它重新连接到仍在运行的旧版本服务。停止服务，然后使用相同的 D2L_HTTP_TOKEN、端口和设置，再次运行同一条 http 命令；从源代码检出版本运行时，请先运行 npm run update。共享服务也会在更新通知中说明这一点。

任何能够使用 bearer token 连接到 Streamable HTTP URL 的其他 MCP 客户端，都可以共用同一服务。若要恢复自动共享服务，请将 command/args 条目改回原样（重新运行 setup，并在它询问是否将 Codex 切回时回答是），然后停止你启动的服务。

当它要求你登录时

无需单独登录——提问时就会登录，而且大多数时候会自动保持登录状态。学校要求再次进行双重验证时，需要批准的数字会直接显示在回答中；在手机上批准后，助手会自动继续检查——每次检查最多等待 45 秒，登录完成后，原问题会立即完成，无需告诉它你已批准。如果你的 AI 客户端会显示工具进度消息，那么在问题仍在处理时就会显示该数字。如果它卡住了，请在终端中运行：

npx -y brightspace-mcp-server@latest auth

**在 Mac 上，**登录时会先从 Keychain 读取已保存的密码。如果你在 Keychain 提示中选择了一次性 允许，之后从 AI 应用或另一个终端登录时可能会失败，或卡在等待一个无人看到的批准请求；请改选 始终允许。此权限仅允许本地 Brightspace 服务读取它自己保存的登录密码，不会读取 Keychain 中的其他内容。

想减少双重验证提示？setup 会询问一个问题：“你希望多久在手机上批准一次登录？”：1 每次都批准（默认），2 记住这台计算机，或 3 让这台计算机自行响应 Microsoft 的验证码请求（需要验证器设置密钥）。选项 2 和 3 为自选，且不适用于共享计算机；如需关闭，请重新运行 setup 并选择 1。相关利弊和获取密钥的步骤见 docs/sign-in.md。

提前退出登录（例如在共享计算机上）时，只需让 AI 应用帮你退出 Brightspace，或在终端中运行 npx -y brightspace-mcp-server@latest auth --logout。这会删除此计算机上保存的 Brightspace 会话，因此下次提问时会完整登录一次。已保存的密码、验证器密钥和设置会保留，因此如果保存了验证器密钥，登录可在没有你操作的情况下完成；在共享计算机上，还要从计算机的密码库中删除已保存的 brightspace-mcp-server 条目（Mac 上的 Keychain Access，Windows 上的 Credential Manager）。此计算机上打开的其他 AI 应用也会退出登录，并在下次提问时要求你登录。（更新前打开的应用可能还会继续回答，最长达一小时；退出并重新打开应用即可立即退出登录。）这只会清除此计算机上的登录状态，不会让你在其他地方退出 Microsoft 或 Brightspace。两种方式也都会取消 AI 应用发起且仍在等待你批准的登录（Windows 上无法通过 auth --logout 取消；它也不会影响另一个终端中运行的 auth，且不会删除任何内容）。取消不会让你更快收到新的提示：Microsoft 要等之前的提示过期后才会发送新的提示，最多可能要等发送后 5 分钟。

需要多久登录一次由你的学校决定，而不是由此工具决定。登录的其他相关内容——Duo、验证器代码、可见浏览器模式，以及完全不使用浏览器运行（Docker、WSL、硬件密钥）——请参阅 docs/sign-in.md。

有什么问题无法正常工作？

• 先运行 npx -y brightspace-mcp-server@latest doctor——它会检查你的 Node 版本、登录浏览器、已保存的设置、凭据存储、Brightspace 连接情况、已保存的登录信息和已安装版本，并准确告诉你需要修复什么。若为全局安装，请运行 brightspace-mcp-server doctor，以检查客户端启动的那份安装。
• 磁盘清理时浏览器被删除了？ 登录时会恢复缺失的 Chromium 下载，并自动重试一次。它使用已安装的 Playwright 依赖项对应的浏览器版本，并保留已保存的凭据、MFA 注册信息和会话。下载限时两分钟；若处于离线状态或修复失败，会返回可执行的安装错误信息，而不是要求你重置凭据。
• 无需登录或更改客户端配置即可修复： 全局安装请运行 brightspace-mcp-server repair，npx 安装请运行 npx -y brightspace-mcp-server@latest repair。自动化时可添加 --json。诊断会打印一条适用于当前正在检查的确切安装的绝对路径命令。修复会验证完整的浏览器可执行文件，并实际启动和关闭无头浏览器。它不会注册客户端、更新学校设置，也不会启动 SSO/MFA。
• 浏览器下载文件可删除；已安装软件包中 node_modules 里的文件属于依赖代码。如果这些文件已被删除，诊断会提供一条限定于该安装的 npm 命令，以先恢复软件包声明的依赖项。浏览器修复不会运行 npm，也不会自动升级软件包。
• Authentication failed: The native credential store is locked or unavailable. 你的密码存储已锁定，或尚未允许此服务读取已保存的密码。请解锁它（在 Mac 上，登录或解锁 Keychain Access），然后再次运行 npx -y brightspace-mcp-server@latest auth；如果仍然失败，请运行 setup，并在 Keychain 询问时选择 始终允许。
• 在终端中能用，但在应用中不能用： 应用会单独启动它，可能尚未访问到你的密码存储——请参阅 docs/troubleshooting.md。
• 应用提示服务启动超时： 打开应用的 MCP 服务日志。每个启动步骤都会在开始前打印带时间戳的 Startup: ... 行，结束时打印 done in N ms；某个步骤运行超过 10 秒时，会打印一次 Startup: still ...。最后一条此类日志会指出卡住的步骤，通常是从密码存储中查找已保存密码。这些日志绝不会包含你的用户名、密码或 Cookie。
• 我使用的是哪个版本？ 询问你的 AI：“我正在运行哪个版本的 Brightspace 服务？”
• 仍然无法解决？ 提交 issue，并粘贴终端输出的内容。

开发者指南

工具参考、响应字段和环境变量：LLMs.md。了解可安全用于构建的内容：STABILITY.md。本项目采用 MIT License 授权。