blackboard-mcp
A read-only MCP server that lets an AI assistant look up a Syracuse Blackboard account's courses, work, and course materials — it can never submit, post, or change anything.
List courses — enumerate the student's visible Blackboard courses and get the course IDs every other tool needs.
Browse course content — list a course's folders, documents, files, assignments, tests, and links, optionally drilling into a specific folder.
Read announcements — per-course announcements, newest first, optionally filtered to those created/modified since a date.
See assignments and due dates — assignments/assessments merged and deduplicated from content, gradebook, and calendar, scopable by course and due-date window, with optional submitted/graded status.
Check grades — the student's own scores, points possible, percentages, feedback, and grading status for a course.
Plan upcoming work — everything due across all courses within the next 1–90 days (default 7), sorted by due date.
Catch up on recent activity — announcements, new or changed content, changed assignments, and newly posted grades since a point in time (default: last 7 days).
Get the full picture for one assignment — instructions, due date, points, rubric, attachments with local file paths, grade/status, and related announcements in a single call.
Download attachments — pull a course file (PDF, DOCX, PPTX, images, text, etc.) to the local machine and return its path, with a text excerpt for small text files.
Read professor-posted links (per the README) — extract content from Google Docs/Sheets/Slides, Drive files, Colab notebooks, Kaltura/Zoom/Panopto media, and other posted pages.
All tools are read-only and stay on the student's own machine; known gaps include discussion boards, course messages, quizzes, journals, attendance, and outside tools like Gradescope or McGraw Hill.
Allows reading content from Google Docs, Sheets, and Colab notebooks linked in Blackboard courses, including handling Google sign-in for private files where possible.
Retrieves metadata for YouTube videos linked in Blackboard courses, such as title, channel, length, and description. Transcripts are not available because YouTube blocks automated access.
Recognizes Zoom links posted in Blackboard courses and can open Zoom recordings after sign-in. Live Zoom meetings are recognized but never opened.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@blackboard-mcp What do I have due this week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Blackboard for Claude
Ask Claude about your own Blackboard and get real answers: what's due, your grades, what your professors posted, and what's inside the files and links they share (PDFs, slides, Google Docs and Sheets, Colab notebooks, SU videos, and more).
It only sees what you can already see, and it can never submit, post, or change anything.

Install (about 5 minutes, one time)
Works on a Mac or a Windows PC. Four steps:
Get Claude Desktop. Download it from claude.ai/download, install it, open it, and sign in. (It's free for Syracuse students.)
Download this file: blackboard-mcp.mcpb It goes into your Downloads folder.
Open your Downloads folder and double-click
blackboard-mcp.mcpb. Claude opens a screen called Blackboard (Syracuse).Click the black Install button. You will see a red box saying the extension "has not been verified by Anthropic" and can access your computer. That is normal for any tool not made by Anthropic itself; this one is a student project. It only reads your Blackboard and the links your professors post, and it never submits or changes anything.
That's it. The tool also needs Google Chrome or Microsoft Edge on your computer. Windows already has Edge, and most Macs already have Chrome. If yours doesn't, Claude will tell you and link you to the free Chrome download.
Double-click didn't open Claude? In Claude, open Settings, click Extensions, and drag
blackboard-mcp.mcpbfrom your Downloads folder into that window.
Related MCP server: Quirkus
The first time you use it
In Claude, ask: "What do I have due this week?"
A new browser window opens with a red banner across the top. It may open behind Claude: if you don't see it, look for a new browser icon in your Dock (Mac) or taskbar (Windows) and click it.
Sign in there with your NetID and approve Duo, like you always do. The window closes by itself when you're done.
Ask your question again.
You're done. You only sign in again when Blackboard logs you out, and when that happens the same red-banner window pops up by itself.
Your password and Duo codes go only into that browser window. Claude never sees them, and this tool never saves them.
Things you can ask
"What's due in the next 7 days?"
"Anything new in my classes this week?"
"What are my grades in Oceanography?"
"Pull up the HW 3 assignment: instructions and attached files."
"Summarize the Week 3 lecture slides."
"What's in the Google Sheet my professor linked in the last announcement?"
"Read the Colab notebook for Lab 0 and explain the first exercise."
Some links need you to be signed in to that site (for example a private Google file or a Zoom recording). When that happens, a red-banner window opens on the link. Sign in there, close that tab, and ask again.
What it can't see
If an answer is missing something, Claude will tell you in that answer, and tell you what to do instead. The known gaps:
Discussion boards, course messages, quiz and test questions, journals, groups, attendance. Not read at all. Open Blackboard for these.
Outside tools launched from Blackboard (McGraw Hill Connect, Gradescope, and similar). Their work and deadlines live in that tool, not in Blackboard.
Deadlines that exist only in class or in a syllabus file. "What's due" only knows what is posted in Blackboard. Ask it to read the syllabus file if you want those too.
YouTube transcripts. YouTube refuses to give transcripts to automated tools, so you get the video's title, channel, length and description. To get the transcript yourself: open the video, click "...more" under it, click "Show transcript", and paste it into the chat.
Live Zoom meetings. A class or office-hours link is recognised but never opened.
Some grades. Only grades your instructor has released are visible. "What's new" can miss a grade entered on an older assignment; ask for a course's grades to be sure.
Google sign-in may be refused. Google sometimes blocks sign-in from automated browser windows. If that happens, ask the professor to share the file as "anyone with the link".
Links from outside your courses. It only opens links a professor posted in one of your courses (see Safety below).
If something goes wrong
What you see | What to do |
Claude doesn't seem to know about Blackboard | Quit Claude completely and open it again (Mac: Cmd + Q. Windows: right-click the Claude icon near the clock and choose Quit). Then check Settings → Extensions shows Blackboard turned on. |
"Sign in in the window with the red banner" | Find that window (it may be behind Claude), sign in with your NetID and Duo, and ask again. |
"This computer has neither Google Chrome nor Microsoft Edge" | Install Google Chrome (free), then ask again. |
"Blackboard is already open in another app" | Another app (like Claude Code) is using Blackboard. Wait a few minutes, or quit that app. |
A course looks empty | Courses from past terms are locked by the university. New courses may have nothing posted yet. |
Something else | Ask again. Blackboard has short hiccups sometimes. |
Update, remove, and privacy
Update: download the file again and double-click it.
Remove: in Claude, open Settings → Extensions, find Blackboard, and remove it.
Erase your login: delete the
.blackboard-mcpfolder in your home folder. It holds your sign-in and any course files it downloaded, and nothing else. Never share that folder.Everything stays on your computer. Nothing is sent anywhere except to Blackboard and the sites your professors link to.
Only your courses' links. It only opens links a professor posted in one of your courses. A web page can hide instructions aimed at the AI; this rule means such a page can never send the AI, or your data, somewhere else. Links to your own computer or home network are refused.
Being a good citizen
Use it for yourself, at a human pace, and check the university's acceptable-use policy before using any automation with your student account. Not affiliated with or endorsed by Syracuse University or Anthology/Blackboard.
Using Claude Code, or setting it up by hand
You need Node.js 22 or newer and git. Then:
Mac
git clone https://github.com/alanwtom/blackboard-mcp.git ~/blackboard-mcp
cd ~/blackboard-mcp
npm run setupWindows (PowerShell)
git clone https://github.com/alanwtom/blackboard-mcp.git ~\blackboard-mcp
cd ~\blackboard-mcp
npm run setupnpm run setup checks for a browser (and offers to download one), connects Claude Desktop and
Claude Code, and opens the sign-in window. To update later: git pull, then npm run setup.
If you already installed the one-click extension, don't also connect Claude Desktop here, or Blackboard will show up twice.
Other commands: npm run login (sign in again), npm run status, npm run courses,
npm run connect -- google (sign in to a site for links), and npm run logout.
Doing every step by hand instead:
Install what it needs (the project comes ready-built, so there is nothing to compile)
npm install --omit=devLog in to Blackboard
npm run loginA browser window opens with a red banner. Sign in with your NetID and approve Duo there. When you land back on Blackboard, the window closes by itself.
Check that it worked
npm run coursesConnect your AI app
For Claude Desktop: open Settings, then Developer, then Edit Config, and add this block inside the outer braces.
On macOS the config lives at ~/Library/Application Support/Claude/claude_desktop_config.json:
"mcpServers": {
"blackboard": {
"command": "node",
"args": ["/Users/yourname/blackboard-mcp/dist/index.js"]
}
}On Windows it lives at %APPDATA%\Claude\claude_desktop_config.json:
"mcpServers": {
"blackboard": {
"command": "C:\\Program Files\\nodejs\\node.exe",
"args": ["C:\\Users\\yourname\\blackboard-mcp\\dist\\index.js"]
}
}Two Windows details matter: every backslash has to be doubled (that is how JSON works; a
single backslash makes the file invalid), and giving the full path to node.exe avoids the
common case where an app launched from the Start menu cannot find node by itself. To print
the two paths you need, run this from the project folder:
(Get-Command node).Source; "$PWD\dist\index.js"On macOS, to print both paths, run this from the project folder:
which node; echo "$PWD/dist/index.js"If Claude Desktop shows no tools even after a full restart, put the which node output in
place of "node" above: an app opened from Finder does not always inherit the PATH your
Terminal has, which is most likely when Node came from nvm or Homebrew.
Save the file, quit Claude Desktop completely (Cmd + Q on a Mac; on Windows right-click the tray icon and choose Quit), and reopen it.
For Claude Code on macOS, run:
claude mcp add --scope user blackboard -- "$(which node)" /path/to/blackboard-mcp/dist/index.jsFor Claude Code on Windows, run this from the project folder:
claude mcp add --scope user blackboard -- "$((Get-Command node).Source)" "$PWD\dist\index.js"For the technically curious
Stack: TypeScript (ESM), Node 22+, Playwright driving Chrome, else Edge, else a downloaded Chromium (remembered per machine, one dedicated profile folder per browser), MCP TypeScript SDK over stdio, Zod, Vitest.
Data access: Blackboard Learn REST API, called as same-origin requests from a page on the Blackboard host, so requests match what the Ultra web app itself sends. Both
blackboard.syr.eduandblackboard.syracuse.edu(separate cookie domains) are supported.Session resilience: Learn's session cookie does not survive a browser restart, so the authenticated cookie set is snapshotted to
~/.blackboard-mcp/browser-state.json(mode 0600 where the OS honours POSIX modes; on Windows the per-user ACL onC:\Users\<name>does that job) and restored on launch. While the institution SSO session lasts, the SAML entry is followed silently to re-authenticate with no interaction.Endpoints (verified against Syracuse, Aug 2026):
users/me,users/{id}/courses?expand=course, course contents (flat listings withparentId; file data oncontentHandler.file), course announcements,calendars/items, and the v2 gradebook (columns,columns/{id}/users/me; due dates atgrading.due, points atscore.possible). Paging caps at 100. Attachment downloads follow the item'srel=alternate/ultra/redirectlink.Tools:
list_courses,get_course_content,get_announcements,get_assignments,get_grades,get_attachment,get_upcoming_work,get_recent_updates,get_assignment_context,read_link. All read-only. Errors are short coded messages with sensitive values masked. Long texts come back in pages (offset/next_offset).Links: every content item, announcement and assignment carries a
linkslist (anchors, iframes and plain-text URLs in its HTML, classified by service).read_linkopens one through the same dedicated browser: Google exports (docx/xlsx/pptx), Drive downloads and folder listings, Colab via Drive, Kaltura captions captured from the player, Zoom recording transcripts from the player's info API (not yet verified against a real recording), Panopto SRT, SharePointdownload=1, GitHub raw/README, and rendered text for everything else. Only links seen in the student's own Blackboard data (plus same-site links on an opened page) are allowed; private and loopback addresses are refused on every redirect hop.File text: PDF (pdf.js via
unpdf), DOCX, PPTX with notes, XLSX with dates (viafflate), notebooks, and plain text formats, all extracted locally.Low volume: TTL caching, a 200 ms delay between pages of the same listing, hard request caps, and the shared browser closes after 5 idle minutes. Independent work (one course versus another, one gradebook column versus another) runs at most four requests deep via
mapWithConcurrency, so the request count is unchanged — they are simply no longer queued behind each other. Courses that answerPERMISSION_DENIEDare remembered for 15 minutes, which removes them from later sweeps entirely: past-term enrolments are reported as available and only refuse when their contents are asked for, and Blackboard publishes no end date to tell them apart beforehand.Configuration:
BB_BROWSER_CHANNEL,BB_HEADLESS=0,BLACKBOARD_MCP_HOME,BB_BASE_URL,BB_SSO_ENTRY_URL, andBLACKBOARD_HOSTSinsrc/blackboard/hosts.tsfor other institutions.One-click extension:
npm run bundlebuildsrelease/blackboard-mcp.mcpb(about 7 MB): the built code, runtime packages only, andextension/manifest.json. Claude Desktop runs it with its own built-in Node (24 as of Sep 2026; the manifest requires 22+). Attach it to a GitHub release under exactly that file name so the "latest" download link keeps working. With no sign-in, the server itself opens the NetID window. With no Chrome or Edge, a terminal install downloads Playwright's Chromium in the background; inside Claude Desktop (which runs extensions in its own Electron process, where spawning "node" would start the Claude app itself) the student is asked to install Chrome instead.BB_PRETEND_NO_BROWSERS=1simulates a machine with neither.Shipped build:
dist/is committed so terminal installs get only runtime packages (about 44 MB) and never compile anything. After changingsrc/, runnpm run buildand commitdist/too; a test fails if it is out of date.npm run setupremoves dev tools fromnode_modules, so runnpm installagain before developing.Development:
npm run typecheck,npm test(fully mocked),npm run build,npm start, andnpm run discover(records real Blackboard traffic while you browse, to verify endpoints).Platforms: macOS, Windows 10/11, and Linux are supported. Linux was tested on Ubuntu 24.04 (the full test suite, the MCP server, and a headless Chromium launch). A fresh Linux machine may need the Chromium system libraries once:
sudo npx playwright install-deps chromium. Everything OS-specific lives insrc/platform.ts(Chrome and Claude Desktop locations, PATH lookup, spawning.cmdshims). Three Windows behaviours the code handles explicitly:Downloaded file names are sanitized to Windows rules on every platform. A Blackboard file called
Week 3: Notes.pdfwould otherwise land in an NTFS alternate data stream on a file namedWeek 3— reported as a successful download the student can never open.A locked browser profile announces itself differently: Windows Chrome exits with code 21 and Playwright only sees the control pipe close, so that signature maps to
BROWSER_PROFILE_BUSYalongside the POSIXSingletonLockmessage.wherelists the extensionless npm shim ahead of the runnable.cmd, so PATH lookups prefer a PATHEXT match, and.cmdshims are spawned throughcmd.exewith quoted arguments (project paths often contain spaces).
Compatibility: built for Syracuse University Blackboard Ultra, Aug 2026. Other schools need the configuration above plus small parser checks.
License
MIT. Made for students, by a student.
Available Tools
10 toolsget_announcementsGet Blackboard course announcementsARead-only
List announcements for one Blackboard course, newest first. Optionally filter to items created or modified after a date. Links inside an announcement are listed under "links"; open one with read_link. Read-only.
Inputs: course_id (required), since.
get_assignment_contextGet full assignment contextARead-only
One package describing a Blackboard assignment: instructions, due date, points, rubric (when available), attached files, links in the instructions (open them with read_link), the student’s grade and submission status, and related course announcements. Use this instead of many low-level calls. status: graded, submitted, in_progress (started or saved as a draft, NOT handed in), not_submitted, or unknown (Blackboard did not say — never treat unknown as missing work). Read-only.
Inputs: assignment_id (required), course_id.
get_assignmentsGet Blackboard assignmentsARead-only
List assignments and assessments with due dates, combined and deduplicated from Blackboard course content, the gradebook, and the calendar. Optionally scope to one course and/or a due-date window. Read-only.
Inputs: course_id, due_after, due_before, include_status.
get_attachmentGet Blackboard course attachmentARead-only
Download a course file (PDF, Word, PowerPoint, Excel, notebooks, text, images, ...) from Blackboard and return its contents as text, plus the local path where it was saved (~/.blackboard-mcp/downloads). PDFs come back page by page, slides with speaker notes, spreadsheets as CSV per sheet. Long files come in pages: pass next_offset back as offset to keep reading. Nothing is sent anywhere. Read-only.
Inputs: course_id (required), content_id (required), offset, file_id.
get_course_contentGet Blackboard course contentARead-only
List a course’s content items (folders, documents, files, assignments, tests, links) from Blackboard. Hierarchy is expanded a couple of folder levels; pass folder_id to go deeper into one folder. Each item lists its "links" (Google Docs/Sheets, Zoom, YouTube, readings...): open one with read_link. Files open with get_attachment. Read-only.
Inputs: course_id (required), folder_id.
get_gradesGet Blackboard gradesARead-only
List the student’s own grades for one Blackboard course: assignment, score, points possible, percentage, feedback, and grading status. Only grades visible to the signed-in student are returned. Read-only.
Inputs: course_id (required).
get_recent_updatesGet recent Blackboard updatesARead-only
Recent Blackboard activity across current courses since a point in time (default: the last 7 days): announcements (with their links), new or changed content items, changed assignments, and grades on gradebook items that changed. Read-only.
Inputs: since.
get_upcoming_workGet upcoming Blackboard workARead-only
Upcoming assignments and assessments across ALL Blackboard courses, sorted by due date, with submission status. Also lists anything due in the last few days that has not been handed in. This is the one call to answer “what do I have due?”. The window runs to the end of the last day, Syracuse time. status: graded, submitted, in_progress (started or saved as a draft, NOT handed in), not_submitted, or unknown (Blackboard did not say — never treat unknown as missing work). Read-only.
Inputs: days.
list_coursesList Blackboard coursesARead-only
List the student’s currently visible Blackboard (Syracuse University) courses. Returns course ids needed by every other blackboard tool. Read-only.
Inputs: no named parameters.
read_linkRead a link posted in BlackboardARead-only
Open a link a professor posted in Blackboard and return what is behind it as text: Google Docs, Sheets (every tab), Slides (with speaker notes), Drive files and folders, Colab notebooks, YouTube videos (title and description; YouTube refuses transcripts), Zoom recordings (transcript, when the host enabled one), Kaltura/Panopto videos (captions), Microsoft 365 and OneDrive files, Google/Microsoft Forms (questions only), GitHub files, PDFs, and ordinary web pages. Links come from the "links" field of get_course_content, get_announcements and get_assignment_context. Only links that appear in the student’s own courses can be opened. Never submits, joins, or types anything. Long results come in pages: pass next_offset back as offset to keep reading. Read-only.
Inputs: url (required), offset, course_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools have clearly distinct purposes, but there is some overlap: get_assignments, get_upcoming_work, get_course_content, and get_assignment_context all surface assignment-related data with different scopes. The descriptions do a good job clarifying when to use each, but an agent could still hesitate between them for certain queries.
All tool names follow a consistent verb_noun snake_case pattern: get_course_content, get_announcements, get_assignments, get_attachment, get_upcoming_work, get_recent_updates, get_assignment_context, get_grades, list_courses, read_link. The verbs get_, list_, and read_ are standard and predictable.
Ten tools is well-scoped for a read-only Blackboard student access server. Each tool earns its place by covering a distinct resource or view (courses, content, announcements, assignments, attachments, links, grades, upcoming work, recent updates, assignment context).
The read-only surface covers the core student workflows: listing courses, browsing content, reading announcements and assignments, opening files and links, checking grades, and tracking due work. A notable gap is discussion/forum reading, and there is no cross-course grade summary, but agents can work around these limitations.
Maintenance
Related MCP Connectors
Your personal data for AI — Telegram, bank, courses, Zoom & more, scoped to you.
Let AI agents use any website you're logged in to. Sessions stay encrypted on your machine.
Build study flashcards and exam-prep decks from your AI chat, all stored locally.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables students to ask an AI assistant about their Canvas LMS data, including assignments, grades, missing submissions, discussions, and upcoming items, while keeping access read-only and private.43MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to read courses, upcoming deadlines, assignment details, grades, announcements, modules, files, inbox, and timetable from U of T Quercus and ACORN through read-only tools.1MIT
- AlicenseNot gradedqualityCmaintenanceLets AI assistants read a student's Canvas LMS/Moodle courses, deadlines, announcements, grades and course files using their normal browser login instead of an access token. It is read-only and keeps all session data and downloads on the user's own machine.35 npm2MIT
- AlicenseAqualityCmaintenanceEnables AI tools such as SlideMate, Claude, and Codex to read a student's Blackboard Learn Ultra courses, content, deadlines, and announcements, and to download lecture slides and readings for the year into per-course folders.91MIT