<h1 align="center">Brightspace D2L MCP Server</h1>

<p align="center">
  <img src="assets/banner.svg" alt="Brightspace D2L MCP server: ask your AI what's due, what you've handed in, your grades and course files" width="100%">
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/brightspace-d2l-mcp"><img src="https://img.shields.io/npm/v/brightspace-d2l-mcp?style=flat-square&label=npm&labelColor=1b2033&color=ff6a3d" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/brightspace-d2l-mcp"><img src="https://img.shields.io/npm/dm/brightspace-d2l-mcp?style=flat-square&label=downloads&labelColor=1b2033&color=ff6a3d" alt="npm downloads per month"></a>
  <a href="https://github.com/AnonymousOnyx22/brightspace-d2l-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/AnonymousOnyx22/brightspace-d2l-mcp/ci.yml?style=flat-square&label=tests&labelColor=1b2033" alt="tests"></a>
  <img src="https://img.shields.io/badge/node-20%2B-3ddc97?style=flat-square&labelColor=1b2033" alt="Node 20+">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-9fb4ff?style=flat-square&labelColor=1b2033" alt="MIT license"></a>
</p>

<p align="center">
  <a href="https://www.producthunt.com/products/brightspace-d2l-mcp-server?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-brightspace-d2l-mcp-server"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1279179&theme=neutral" alt="Brightspace D2L MCP Server on Product Hunt" width="250" height="54"></a>
</p>

<h3 align="center">Connect D2L Brightspace to Claude, ChatGPT, Cursor and Copilot.<br>It knows what you already handed in, so it only shows what is actually left.</h3>

<p align="center">One command. Sign in the way you always do. No passwords stored.</p>

<p align="center"><a href="https://brightspace-mcp.netlify.app"><b>brightspace-mcp.netlify.app</b></a></p>

<br>

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI assistants and agents read access to your Brightspace courses: due dates with real submission status, grades, assignments, rubrics, course content, announcements, discussions and class lists. It works at any school that uses D2L Brightspace, including schools with Microsoft, Duo, Okta or Shibboleth single sign-on.

## Quick start

You need [Node.js 20 or newer](https://nodejs.org/) and Google Chrome or Microsoft Edge.

```bash
npx brightspace-d2l-mcp setup
```

That's it. Setup asks for your school, opens a browser so you can sign in, and connects every AI app it finds.
Then ask your AI:

> **"What should I work on right now?"**

<p align="center">
  <img src="assets/demo.gif" alt="Asking an AI what to work on and getting a Brightspace to-do list that skips submitted work (sample data)" width="760">
</p>

<p align="center">
  <img src="assets/setup.svg" alt="The setup command finding the school, signing in, and connecting AI apps" width="760">
</p>

New to this? The **[step-by-step setup guide](docs/setup.md)** walks through everything with pictures of each step.
Using a specific app? See the guides for **[Claude](https://brightspace-mcp.netlify.app/claude/)** and **[ChatGPT](https://brightspace-mcp.netlify.app/chatgpt/)**, or **[how this compares](https://brightspace-mcp.netlify.app/compare/)** to other Brightspace MCP servers.

## How it compares

People usually weigh a few Brightspace MCP servers before picking one. Here are the three differences that come up most, with the [full comparison](https://brightspace-mcp.netlify.app/compare/) for the rest:

| Server | Submission status | Sign-in (SSO) | Target grade |
|---|---|---|---|
| **Brightspace MCP** (this repo, `brightspace-d2l-mcp`) | Every due date says whether you already handed the work in, and the to-do list skips what is done | Real browser window where you sign in yourself, so any SSO works: Microsoft, Duo, Okta, Shibboleth. No password stored | `get_grade_outlook` gives your current percentage, your best and worst possible final grade, and what you need on the remaining work to hit any target |
| [brightspace-mcp-server](https://www.npmjs.com/package/brightspace-mcp-server) by RohanMuppa | Shown in its assignments tool | Automated sign-in that saves your password in Keychain or Credential Manager, with presets for nine schools | No target-grade tool in its published list |
| [brightspace-mcp](https://www.npmjs.com/package/brightspace-mcp) by JhostinAleck | Lists the files you submitted | Configured automation: HTTP login, headless browser with a Microsoft preset, Duo push, or pasted cookies | `grade_audit` answers "what you need to pass" |
| [@n35da/brightspace-mcp](https://www.npmjs.com/package/@n35da/brightspace-mcp) | Shown on each dropbox folder | Real browser window where you sign in with your school's SSO | No target-grade tool in its published list |
| [@exhabition/brightspace-mcp](https://www.npmjs.com/package/@exhabition/brightspace-mcp) (Rust) | Has assignment and submission readers | Visible Chromium window, Microsoft SSO only | No target-grade tool in its published list |

"No target-grade tool in its published list" means we could not find one in each project's public README and tool list as of October 2026, not that it can never be added. Spot a mistake in the table? Open an issue and it will be fixed.

## Switching from brightspace-mcp-server

If you are running [brightspace-mcp-server](https://www.npmjs.com/package/brightspace-mcp-server) by RohanMuppa and want to try this one, you only change the package name. Everything else stays where it is.

In your MCP config, find the `brightspace` entry inside `mcpServers` and swap the command:

```json
{
  "mcpServers": {
    "brightspace": {
      "command": "npx",
      "args": ["-y", "brightspace-d2l-mcp@latest"]
    }
  }
}
```

On Windows, wrap the launch in `cmd /c` the same way you do now:

```json
{
  "mcpServers": {
    "brightspace": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "brightspace-d2l-mcp@latest"]
    }
  }
}
```

Then restart the app. If you would rather not edit files, run `npx brightspace-d2l-mcp setup`: it asks for your school, opens a browser window so you sign in, and writes this entry for you. You can also print the exact JSON for any app with `npx brightspace-d2l-mcp config`.

### What carries over and what doesn't

| | Status |
|---|---|
| The `brightspace` server name in `mcpServers` | Same here, so a config entry and any saved prompt that points at the `brightspace` server still lines up |
| Tool names | They differ. See which tools this one has in the [Tools](#tools) table above and ask your AI for those names instead |
| Your Brightspace account and courses | Nothing to move. This server signs in as you and sees the courses you are enrolled in, same as before |
| A `D2L_INCLUDE_COURSES` or `D2L_EXCLUDE_COURSES` setting | Both names are read here too, so a course filter in your env block keeps working. `D2L_ACTIVE_ONLY` behaves the same way and is read here as well |
| Whatever the first server saved on your computer | It is left alone. This server stores its own settings and session in `~/.brightspace-d2l-mcp/`, so nothing there changes unless you remove it yourself |

Want to go back? Put the old command back in the same spot. Both servers can even be configured side by side under two different server names, but one AI app talking to two Brightspace servers at once tends to be more confusing than it is worth.

A few things the first server does are not done here: it can sign you in without a browser window by saving your password in your computer's credential store, and it ships presets for several named schools. This server always opens a normal browser window where you sign in yourself, which is what makes any single sign-on work, and all it keeps afterward is your browser session.

## What you can ask

| | Try asking |
|---|---|
| ✅ **What's left** | "What should I work on right now?" · "What haven't I submitted yet?" |
| 📅 **Deadlines** | "What's due this week?" · "Anything due tomorrow?" |
| 📊 **Grades** | "What are my grades?" · "Am I passing Calculus?" |
| 📢 **Announcements** | "Did any professor post something today?" |
| 📚 **Course content** | "Find the midterm review slides" · "Summarize the Lab 3 instructions" |
| 📎 **Assignment files** | "What does the rubric for the project ask for?" |
| 💬 **Discussions** | "What are people saying in the final project thread?" |
| 👥 **Class list** | "Who's the TA for my networking course?" |
| 🎯 **Target grade** | "What do I need on the final to get an 80?" · "Can I still pass?" |
| 🗓️ **Calendar** | "Put my deadlines in my calendar" |
| 📝 **Exams** | "When is my midterm?" · "What's on my schedule this week?" |
| 🔔 **What's new** | "Catch me up" · "Did anything get graded?" |

### It knows what you've already handed in

Most tools only see due dates, so they keep telling you to do work you've finished.
This one checks your actual submission for every assignment:

| Status | Meaning |
|---|---|
| `submitted` / `graded` | Done. Never suggested as a to-do. |
| `not_submitted` / `draft` | Still needs doing. |
| `not_open_yet` | The dropbox hasn't opened; shows when it will. |
| `closed` / `past_due` | You can no longer submit. |
| `unknown` | Quizzes: Brightspace doesn't show students their quiz attempts, so your AI will ask you. |

## Tools

17 MCP tools for D2L Brightspace. Everything reads from Brightspace and nothing is ever changed there:

| Tool | What it does |
|---|---|
| `get_todo` | Prioritized to-do list across every course: what's due soon, overdue, not open yet, and already done |
| `get_upcoming_due_dates` | Upcoming deadlines with the real submission status of each assignment |
| `get_my_courses` | Your enrolled courses with names, codes and ids |
| `get_my_grades` | Grade breakdown per course with points, percentages and instructor comments |
| `get_assignments` | Assignments (dropboxes) and quizzes with due dates, status and rubrics |
| `get_assignment_files` | Reads the instructions, handouts and rubric files attached to an assignment |
| `get_course_content` | Course modules, lecture slides, files and links |
| `get_syllabus` | Course syllabus and overview |
| `get_announcements` | Recent announcements (news) from your instructors |
| `get_discussions` | Discussion forums, topics and posts |
| `get_roster` | Instructors and TAs with contact info, optionally the full class list |
| `get_classlist_emails` | Email addresses for everyone in a course |
| `download_file` | Saves a course file or submission to a folder you choose |
| `get_grade_outlook` | Where you stand in a course and what you need on the remaining work to hit a target grade |
| `export_due_dates_calendar` | Builds a calendar file (.ics) of your unfinished deadlines for Google Calendar, Apple Calendar and Outlook |
| `get_calendar_events` | Exams, tests, labs, classes and other events from your course calendars |
| `get_whats_new` | Catch-up across every course: new announcements, newly marked work, unread discussions and untried quizzes |

### Built-in prompts

Apps that support MCP prompts show these as one-click shortcuts or slash commands:
`what_should_i_do_now` · `plan_my_week` · `weekly_digest` · `grade_target` · `exam_prep` · `summarize_assignment` · `put_deadlines_in_my_calendar` · `catch_me_up` · `when_are_my_exams`

## Works at any Brightspace school

Every school signs in differently: Microsoft, ADFS, Duo, Shibboleth, Okta, Google, campus pickers, or Brightspace's own form.
Instead of guessing how your school works, setup opens a **normal browser window** and you sign in exactly like you do every day, text codes and authenticator apps included.

<p align="center">
  <img src="assets/how-it-works.svg" alt="Your AI app talks to this server on your computer, which reads Brightspace with the session from your browser sign-in" width="860">
</p>

After that it stays signed in quietly in the background. If your school ever asks you to sign in again, the browser window simply pops up and closes by itself when you're done.

## Does my school work?

If your school uses D2L Brightspace, yes. Setup opens a normal browser window so any sign-in works, including Microsoft, Duo, Okta and Shibboleth.

| School | Status |
|---|---|
| One college | Tested by the author |
| Any other D2L school | Should work. Open an issue with yours and I will add it here |

## Works with your AI app or agent

**Connected automatically by setup:**
Claude Desktop · Claude Code · Cursor · VS Code (GitHub Copilot) · Windsurf · OpenAI Codex · Gemini CLI · Cline · Roo Code · OpenCode · Zed · LM Studio · Kiro

**One copy-paste away:**
ChatGPT (developer mode) · Continue · Goose · JetBrains AI Assistant · Warp · Amp · Msty · Jan · AnythingLLM

**Agent frameworks:**
OpenAI Agents SDK · Claude Agent SDK · LangChain / LangGraph · Vercel AI SDK · Mastra · CrewAI · Pydantic AI · LlamaIndex

It runs over **stdio** for local apps and **streamable HTTP** (`serve --http`) for ChatGPT and hosted agents.
See **[docs/agents.md](docs/agents.md)** for copy-paste setup for every one of these.

## Install it with your AI

Paste this into Claude Code, Cursor, Windsurf, Copilot or Codex and it will set everything up for you.

```text
Install brightspace-d2l-mcp for me by following
https://github.com/AnonymousOnyx22/brightspace-d2l-mcp/blob/main/llms.txt
```

## Commands

| Command | What it does |
|---|---|
| `npx brightspace-d2l-mcp setup` | Pick your school, sign in, connect your AI apps. On Windows the window closes by itself when done (`--keep-open` to stop that) |
| `npx brightspace-d2l-mcp login` | Sign in again |
| `npx brightspace-d2l-mcp status` | Show your school, whether you're signed in, and connected apps |
| `npx brightspace-d2l-mcp doctor` | Check Node, your school, sign-in and connected apps, and say how to fix anything wrong |
| `npx brightspace-d2l-mcp logout` | Delete the saved session |
| `npx brightspace-d2l-mcp uninstall` | Remove from all AI apps and delete all local data |
| `npx brightspace-d2l-mcp serve --http` | Run over HTTP for ChatGPT and HTTP-based agents |
| `npx brightspace-d2l-mcp config` | Print the MCP config JSON for any other app |

When a newer version is out, commands ask whether to update first. Set `BRIGHTSPACE_NO_UPDATE_CHECK=1` to turn that off.

<details>
<summary><b>Setup options</b></summary>

```bash
npx brightspace-d2l-mcp setup --school yourschool.brightspace.com   # skip the school question
npx brightspace-d2l-mcp setup --apps claude-desktop,cursor          # only connect these apps
npx brightspace-d2l-mcp setup --skip-login                          # sign in later, on first use
npx brightspace-d2l-mcp setup --yes                                 # accept every default
```

App ids: `claude-desktop`, `claude-code`, `cursor`, `vscode`, `windsurf`, `codex`, `gemini-cli`, `cline`, `roo-code`, `opencode`, `zed`, `lm-studio`, `kiro`.

</details>

## Privacy and security

- **Your password is never seen or stored.** You type it into your school's own sign-in page in a real browser.
- **Read-only.** It can't submit, post, or change anything in Brightspace. No tool sends anything but GET requests, the API client has no write methods at all, and a test fails the build if one is ever added. See [how read-only is enforced](SECURITY.md#how-read-only-is-enforced).
- **Local only.** Everything runs on your computer and talks only to your school's Brightspace. There's no server in between, and no analytics.
- **Uses the official Brightspace API** with the same access you have in your browser.
- Your session is saved in `~/.brightspace-d2l-mcp/`, readable only by your user account. `logout` deletes it; `uninstall` deletes everything.

## Troubleshooting

Something not working? **[docs/troubleshooting.md](docs/troubleshooting.md)** walks through an app that shows no Brightspace tools, a setup window that never opens, and a single sign on that keeps failing, with the exact message each one prints. It starts with `npx brightspace-d2l-mcp doctor`.

<details>
<summary><b>"No supported browser was found"</b></summary>

Install [Google Chrome](https://www.google.com/chrome/) or use Microsoft Edge (already on Windows).
Or install a private copy of Chromium with `npx playwright install chromium`.
</details>

<details>
<summary><b>My school address isn't accepted</b></summary>

Sign in to Brightspace in your browser, then copy the address from the address bar (any page works).
If it says your site "runs Blackboard" or "Canvas", your school doesn't use Brightspace.
</details>

<details>
<summary><b>Brightspace doesn't show up in Claude Desktop</b></summary>

Fully quit Claude Desktop (tray icon → Quit, not just closing the window), then run `setup` again.
Claude Desktop rewrites its settings while it's open, so setup offers to restart it for you.
</details>

<details>
<summary><b>It keeps asking me to sign in</b></summary>

Some schools end sessions every few hours. When that happens a browser window opens so you can sign in again.
Run `npx brightspace-d2l-mcp doctor` to find out what is wrong, `status` for a quick look, or `login` to sign in right away.
If you'd rather it never opens a window on its own, add `"autoLogin": false` to `~/.brightspace-d2l-mcp/config.json`.
</details>

<details>
<summary><b>I want to filter out old courses</b></summary>

Add course ids to `~/.brightspace-d2l-mcp/config.json`:

```json
{ "excludeCourses": [123456, 789012] }
```

Or keep only specific ones with `"includeCourses"`. Ask your AI "list my courses with their ids" to find them.
</details>

## FAQ

<details>
<summary><b>How do I connect D2L Brightspace to Claude?</b></summary>

Run `npx brightspace-d2l-mcp setup`. It connects Claude Desktop and Claude Code automatically. Then ask Claude about your courses.
</details>

<details>
<summary><b>Is there an AI assistant for D2L Brightspace?</b></summary>

Yes. This connects Brightspace to the AI app you already use (Claude, ChatGPT, Cursor, GitHub Copilot, Gemini and others), so you can ask about deadlines, grades and course files in plain English instead of clicking through every course.
</details>

<details>
<summary><b>How do I use ChatGPT with Brightspace?</b></summary>

Run `npx brightspace-d2l-mcp serve --http`, expose it with a tunnel, and add the URL as a connector in ChatGPT developer mode. [docs/agents.md](docs/agents.md#chatgpt) walks through each step.
</details>

<details>
<summary><b>How do I connect Brightspace to Cursor, VS Code Copilot or Windsurf?</b></summary>

Run `npx brightspace-d2l-mcp setup`. It finds Cursor, VS Code, Windsurf and 10 other apps and connects them for you.
</details>

<details>
<summary><b>Can I use this with ChatGPT, a custom agent, or the Claude Agent SDK?</b></summary>

Yes. Local agents and SDKs launch it with `npx -y brightspace-d2l-mcp@latest`, and ChatGPT or HTTP-based agents use `npx brightspace-d2l-mcp serve --http`. [docs/agents.md](docs/agents.md) has copy-paste setup for ChatGPT, the OpenAI Agents SDK, Claude Agent SDK, LangChain, Vercel AI SDK and more.
</details>

<details>
<summary><b>Does it need an API key or admin access from my school?</b></summary>

No. Brightspace API keys normally require an administrator. This uses your own student sign-in instead, so it sees exactly what you see in Brightspace, and nobody at your school has to set anything up.
</details>

<details>
<summary><b>How do I switch from brightspace-mcp-server to this one?</b></summary>

Change the package name in your MCP config: replace `brightspace-mcp-server` with `brightspace-d2l-mcp` in the same `brightspace` entry, then restart the app. Or run `npx brightspace-d2l-mcp setup` and let it write the entry for you. [Switching from brightspace-mcp-server](#switching-from-brightspace-mcp-server) covers what carries over and what does not.
</details>

<details>
<summary><b>Does it work with Duo, Microsoft Authenticator or text-message codes?</b></summary>

Yes. You sign in yourself in a real browser window, so any sign-in method your school uses works.
</details>

<details>
<summary><b>Can it tell me what I need on my final to reach a grade?</b></summary>

Yes. Ask "what do I need on the final to get an 80 in Calculus?" and `get_grade_outlook` uses the weights Brightspace reports to give your current percentage, your best and worst possible final grade, and the average you need on everything left.
</details>

<details>
<summary><b>Can I get my Brightspace due dates in Google Calendar, Apple Calendar or Outlook?</b></summary>

Yes. Ask your AI to put your deadlines in your calendar. `export_due_dates_calendar` makes an .ics file with a link back to Brightspace and a one day reminder on each event, and only includes work you have not handed in.
</details>

<details>
<summary><b>Which schools does it work with?</b></summary>

Any school on D2L Brightspace, whether the address looks like `yourschool.brightspace.com`, `yourschool.desire2learn.com`, or a custom domain like `learn.yourschool.edu`.
</details>

<details>
<summary><b>Can it submit assignments or post for me?</b></summary>

No. It's read-only on purpose.
</details>

<details>
<summary><b>Is this made by D2L?</b></summary>

No. It's an independent open-source project that uses the official Brightspace API with your own sign-in. It isn't affiliated with or endorsed by D2L.
</details>

## Development

```bash
git clone https://github.com/AnonymousOnyx22/brightspace-d2l-mcp.git
cd brightspace-d2l-mcp
npm install
npm run build
npm test
node build/index.js setup     # connects your AI apps to this local build
```

Tools live in [`src/tools/`](src/tools), sign-in in [`src/auth/`](src/auth), and setup in [`src/cli/`](src/cli).
Issues and pull requests are welcome.

## More free student MCP servers

All free, open source and read only where they touch your accounts. Browse the full list at [brightspacemcp.com/more-mcps](https://brightspacemcp.com/more-mcps/).

| Server | What it does |
| --- | --- |
| [Canvas MCP](https://github.com/AnonymousOnyx22/canvas-lms-student-mcp) | Canvas LMS for AI, read only. Due dates, missing work, grades and announcements. |
| [Moodle MCP](https://github.com/AnonymousOnyx22/moodle-student-mcp) | Moodle for AI, read only. Due dates, overdue work, grades and announcements. |
| [Google Classroom MCP](https://github.com/AnonymousOnyx22/google-classroom-student-mcp) | Google Classroom for AI, read only. Todos, due dates, missing work and grades. |
| [GPA Calculator MCP](https://github.com/AnonymousOnyx22/gpa-calculator-mcp) | GPA, grade conversion and the grade you need on the final, for AI. Works offline, no account. |
| [Citations MCP](https://github.com/AnonymousOnyx22/student-citations-mcp) | APA, MLA and Chicago citations from a DOI, an ISBN or typed details. No account. |
| [Study Planner MCP](https://github.com/AnonymousOnyx22/study-planner-mcp) | Exam study schedules, spaced repetition dates, pomodoro plans and assignment milestones. Works offline. |
| [Paper Finder MCP](https://github.com/AnonymousOnyx22/paper-finder-student-mcp) | Search scholarly papers, find open access copies and related work through OpenAlex. No key needed. |

## License

[MIT](LICENSE) © AnonymousOnyx22

D2L and Brightspace are trademarks of D2L Corporation. This project is not affiliated with D2L.