brightspace-mcp
📖 Full documentation site →
MCP server for D2L Brightspace. Gives Claude (and any MCP-compatible client) access to your courses, grades, assignments, content, calendar, and more — with multi-strategy authentication, full MFA support, and production-grade resilience built in.
Quick start
npx brightspace-mcp@latest setup
The interactive wizard handles everything: base URL, auth strategy, MFA, credential storage, and auto-registration with Claude Desktop / Cursor / Windsurf.
For CI pipelines or DevContainers with no TTY, use the non-interactive init command instead:
npx brightspace-mcp@latest init \
--base-url https://yourschool.brightspace.com \
--strategy api_token \
--token-ref env:BRIGHTSPACE_API_TOKEN
Documentation
Deep-dive guides live in docs/ — start with docs/README.md.
For AI assistants and contributors, AGENTS.md is a one-page map of the repo.
Table of contents
Installation
npx (recommended — no install needed)
npx brightspace-mcp@latest setup
npx brightspace-mcp@latest serve
Global install
npm install -g brightspace-mcp
brightspace-mcp setup
brightspace-mcp serve
From source
git clone https://github.com/JhostinAleck/brightspace-mcp.git
cd brightspace-mcp
npm install && npm run build
node build/cli/main.js serve
Requirements: Node.js ≥ 20.
Staying up to date
- npx (recommended) — the MCP client config written by
setup runs npx --yes brightspace-mcp@latest serve, so every client restart picks up the newest release. Nothing else to do.
- Global install —
npm install -g brightspace-mcp@latest (brightspace-mcp upgrade checks npm and prints the right command).
- Docker —
docker pull the latest image and recreate the container.
The server checks npm at most once a day (3 s timeout, cached in ~/.brightspace-mcp/update-check.json). When a newer version exists — or when your installed version has been deprecated because of a security fix — the notice is appended to the first tool response of the session, so your assistant tells you about it. It also shows up under update in get_diagnostics. Set BRIGHTSPACE_NO_UPDATE_CHECK=1 to opt out.
Authentication strategies
Pick the strategy that matches your Brightspace setup. Run npx brightspace-mcp@latest setup and it will walk you through the right one.
API Token (simplest)
Requires a Valence API token from your Brightspace admin panel.
profiles:
my_school:
base_url: https://school.brightspace.com
auth:
strategy: api_token
api_token:
token_ref: env:BRIGHTSPACE_API_TOKEN
export BRIGHTSPACE_API_TOKEN="your-token"
npx brightspace-mcp@latest serve
Headless (username + password)
Automates HTTP-level login — no browser window. Supports all MFA strategies including Duo Push.
profiles:
my_school:
base_url: https://school.brightspace.com
auth:
strategy: headless
headless:
login_url: https://school.brightspace.com/d2l/login
username_ref: env:BRIGHTSPACE_USERNAME
password_ref: env:BRIGHTSPACE_PASSWORD
mfa:
strategy: duo_push
duo_push: {}
Browser (Playwright)
Launches a headless Chromium instance and automates the login UI. Best for SSO flows (Microsoft Azure AD, SAML) where the login page has complex JavaScript.
npm install playwright && npx playwright install chromium
auth:
strategy: browser
browser:
login_url: https://school.brightspace.com/d2l/login
headless: true
username_ref: env:BRIGHTSPACE_USERNAME
password_ref: env:BRIGHTSPACE_PASSWORD
selectors:
username: "#i0116"
password: "#i0118"
submit: "#idSIButton9"
password_submit: "#idSIButton9"
mfa_input: "#idTxtBx_SAOTCC_OTC"
mfa_submit: "#idSubmit_SAOTCC_Continue"
post_login: "d2l-labs-navigation"
mfa:
strategy: totp
totp:
secret_ref: env:BRIGHTSPACE_TOTP_SECRET
The setup wizard includes a Microsoft SSO preset that fills all selectors automatically.
Session Cookie
Paste the D2L session cookies from your browser's DevTools. Useful when other strategies are blocked.
auth:
strategy: session_cookie
session_cookie:
cookie_ref: env:BRIGHTSPACE_COOKIE
session_ttl_seconds: 3600
export BRIGHTSPACE_COOKIE="d2lSessionVal=...; d2lSecureSessionVal=..."
MFA strategies
| Strategy | When to use |
|---|
none | No MFA on your account |
totp | Authenticator app (Google Authenticator, Authy, etc.) |
duo_push | Duo Security — server polls for mobile approval automatically |
manual_prompt | Any TOTP/OTP — server pauses and asks you to paste the code |
TOTP example
mfa:
strategy: totp
totp:
secret_ref: env:BRIGHTSPACE_TOTP_SECRET
digits: 6
period: 30
algorithm: SHA1
Duo Push example
mfa:
strategy: duo_push
duo_push:
poll_interval_ms: 1000
timeout_ms: 120000
Configuration reference
Full config file (~/.brightspace-mcp/config.yaml):
default_profile: my_school
profiles:
my_school:
base_url: https://school.brightspace.com
auth:
strategy: api_token
api_token:
token_ref: env:BRIGHTSPACE_API_TOKEN
session:
cache_backend: memory
preemptive_refresh_seconds: 300
output:
tz: America/Bogota
locale: es-419
format: markdown
include_meta_footer: true
logging:
level: info
writes:
enabled: false
dry_run: false
redis:
url: redis://localhost:6379
key_prefix: "brightspace:"
Credential references
Secret values are never stored in plain text. Use ref: notation to point to the actual value:
| Prefix | Example | Description |
|---|
env:NAME | env:BRIGHTSPACE_API_TOKEN | Read from environment variable |
keychain:service/account | keychain:brightspace-mcp/token | OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager) |
file:label | file:api_token | Encrypted file (~/.brightspace-mcp/credentials.enc, AES-256-GCM) |
Output: timezone and language
All tool responses are formatted in your configured timezone and language.
output:
tz: America/Bogota
locale: es-419
format: markdown
include_meta_footer: true
Run brightspace-mcp setup and choose your timezone and language. Or set it in ~/.brightspace-mcp/config.yaml.
Redis cache
When running multiple instances or want cache persistence across restarts, enable Redis:
1. Add the redis section to config:
redis:
url: redis://localhost:6379
key_prefix: "brightspace:"
profiles:
my_school:
session:
cache_backend: redis
2. Install ioredis (optional dependency):
3. Start Redis and the server:
docker run -d -p 6379:6379 redis:7-alpine
npx brightspace-mcp@latest serve
The domain cache (courses, grades, assignments, etc.) automatically uses Redis as persistent layer when the redis: section is present in config. Session tokens are stored with TTL derived from the token expiry.
Write operations
Write tools (submit_assignment, post_discussion_reply, mark_announcement_read) are disabled by default and require two separate opt-ins:
1. Config file:
writes:
enabled: true
dry_run: false
2. CLI flag:
npx brightspace-mcp@latest serve --enable-writes
All write operations:
- Require a client-supplied
idempotency_key (8–128 chars). Repeat calls with the same key return the cached response without re-executing.
- Emit a WARN-level audit log line with correlation ID, tool name, and redacted args.
- Respect
dry_run: true to return a preview response without touching D2L.
| Tool | Description |
|---|
check_auth | Verify authentication and show the active user identity |
list_my_courses | List all enrolled courses |
get_my_grades | Get grades for a course |
get_assignments | List assignments and dropbox folders |
get_assignment_files | Download and read instructor-posted assignment files |
get_upcoming_due_dates | List assignments due in the next N days |
get_feedback | Read the grade, instructor comments and per-criterion rubric results for an assignment |
get_assignment_rubric | Show an assignment's grading rubric (criteria, levels, points, descriptions) |
get_my_submissions | List and download the files you (or your group) submitted, even after the folder closes |
get_syllabus | Fetch the course syllabus |
get_course_content | Browse modules and topics (includes topic IDs) |
get_topic_file | Download and read a content topic file (DOCX, PDF, HTML, plain text) |
get_announcements | List course announcements (excerpt, author, attachments) |
get_announcement | Read one announcement in full, or one of its attachments |
get_discussions | Browse discussion forums and threads |
get_calendar_events | List calendar events in a date range |
get_roster | Get the full course roster |
get_classlist_emails | Get classmate email addresses |
get_my_groups | List group enrollments per course with member rosters |
list_quizzes | List quizzes with attempt counts, time limits, due dates |
get_quiz_attempts | Your attempts on a quiz with scores and timestamps |
list_notifications | User activity feed (announcements, due-date reminders, grade releases) |
search_course | Full-text search across content, announcements, and discussions |
get_audit_log | Local history of write operations (correlation IDs, redacted args) |
get_diagnostics | Show cache stats, circuit breaker state, and version info |
clear_cache | Clear memory and persistent cache backends |
| Tool | Description |
|---|
submit_assignment | Upload a file to a Brightspace Dropbox folder |
post_discussion_reply | Reply to a discussion thread |
mark_announcement_read | Mark an announcement as read |
MCP Resources
Four stable URIs for Brightspace content (readable by any MCP client via resources/read):
| URI | Content |
|---|
brightspace://{courseId}/syllabus | Course syllabus, HTML stripped |
brightspace://{courseId}/content/topics/{topicId} | Topic file (text extracted from PDF, or base64 fallback) |
brightspace://{courseId}/assignments/{assignmentId}/files | All assignment attachments as text |
brightspace://{courseId}/announcements/{announcementId} | Announcement text |
Obtain IDs from tools like list_my_courses, get_assignments, get_announcements.
MCP Prompts
Four pre-built prompt templates visible in your MCP client's prompt picker:
| Prompt | Arguments | Purpose |
|---|
weekly_briefing | none | 7-day overview: due dates, announcements, recent grades |
grade_audit | course_id? | Grade analysis + what you need to pass |
study_planner | days_ahead? (default 7) | Study plan from due dates and calendar |
course_summary | course_id (required) | Full course overview |
TUI dashboard
brightspace-mcp tui
brightspace-mcp tui --profile work
Full-screen interactive terminal UI (Ink + React). Six tabs navigated with Tab / → / ←:
| Tab | Contents |
|---|
| Inicio | 3-column dashboard: upcoming assignments, 7-day calendar agenda, recent announcements |
| Cursos | Live-search course list → drill into a course → sub-tabs Tareas / Notas / Anuncios |
| Calendario | 30-day event agenda across all active courses |
| Config | Profile summary, field-by-field form editor (dropdowns from schema), or the config path to edit in your own editor + validation |
| Caché | Hit rate, miss count, clear button |
| Logs | Audit log (last 50 entries, / to filter by tool name) |
Press Ctrl+C to exit.
Register with an MCP client
See docs/clients.md for Claude Desktop, Cursor, and Windsurf snippets, or run brightspace-mcp setup which auto-detects and registers for you.
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"brightspace": {
"command": "npx",
"args": ["--yes", "brightspace-mcp@latest", "serve"],
"env": {
"BRIGHTSPACE_CONFIG": "/Users/you/.brightspace-mcp/config.yaml"
}
}
}
}
CLI reference
npx brightspace-mcp@latest setup Interactive first-time setup wizard (detects system language)
npx brightspace-mcp@latest init [flags] Non-interactive config writer (CI/scripts, no TTY)
npx brightspace-mcp@latest serve Start the MCP server (stdio transport)
npx brightspace-mcp@latest serve --enable-writes Start with write tools enabled
npx brightspace-mcp@latest tui Full-screen terminal dashboard (Ink TUI)
npx brightspace-mcp@latest auth Re-authenticate and test the config
npx brightspace-mcp@latest record-auth Open browser for manual login, capture session cookies
npx brightspace-mcp@latest doctor End-to-end smoke test: config → auth → API → list_my_courses
npx brightspace-mcp@latest profile list List profiles (* marks the default)
npx brightspace-mcp@latest profile use <name> Switch the default profile
npx brightspace-mcp@latest config show Print config (secrets redacted)
npx brightspace-mcp@latest config show --resolved Show all secret refs as [redacted]
npx brightspace-mcp@latest config validate Validate config schema without running
npx brightspace-mcp@latest config set <path> <value> Edit a nested config value
npx brightspace-mcp@latest cache clear Clear memory + file/Redis cache
npx brightspace-mcp@latest cache clear --context <n> Clear a specific cache context
npx brightspace-mcp@latest upgrade Check npm and print the upgrade command
Docker
Standalone
docker pull ghcr.io/jhostinaleck/brightspace-mcp:latest
docker run --rm -i \
-v "$HOME/.brightspace-mcp:/config:ro" \
-e BRIGHTSPACE_CONFIG=/config/config.yaml \
ghcr.io/jhostinaleck/brightspace-mcp:latest serve
With Redis (docker-compose)
docker compose --profile redis up
docker compose up
The config.yaml inside ~/.brightspace-mcp/ must have the redis: section pointing to redis://redis:6379 when using the compose profile.
Architecture highlights
- Resilience: retry with exponential backoff + jitter, circuit breaker (5 failures → 30s cooldown), request coalescing, bulkhead (max 5 concurrent requests)
- Cache tiers: HTTP response cache (L1, in-memory, 60s TTL) + domain cache (L2, layered memory → file or Redis)
- Security: HTTPS-only transport, secrets redaction in all log output, OS keychain integration, AES-256-GCM encrypted credential file, session tokens expire with the D2L token
- DDD structure: bounded contexts (
assignments, authentication, calendar, communications, content, courses, grades, groups, notifications, quizzes) with clean domain / application / infrastructure separation
License
MIT © Jhostin Aleck