Brightspace

brightspace-mcp

[CI] [Docs] [npm version] [License: MIT] [Node.js]

📖 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   # interactive wizard (recommended for first time)

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
• Authentication strategies
• MFA strategies
• Configuration reference
• Output: timezone and language
• Redis cache
• Write operations
• Available tools
• MCP Resources
• MCP Prompts
• TUI dashboard
• Register with an MCP client
• CLI reference
• Docker

Installation

npx (recommended — no install needed)

npx brightspace-mcp@latest setup   # first-time wizardnpx brightspace-mcp@latest serve   # run the server

Global install

npm install -g brightspace-mcpbrightspace-mcp setupbrightspace-mcp serve

From source

git clone https://github.com/JhostinAleck/brightspace-mcp.gitcd brightspace-mcpnpm install && npm run buildnode 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     # or: totp, manual_prompt, none          duo_push: {}           # uses defaults: poll every 1s, timeout 120s

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

# Cookie format: "d2lSessionVal=XXX; d2lSecureSessionVal=YYY"export BRIGHTSPACE_COOKIE="d2lSessionVal=...; d2lSecureSessionVal=..."

MFA strategies

TOTP example

mfa:  strategy: totp  totp:    secret_ref: env:BRIGHTSPACE_TOTP_SECRET   # base32 secret from QR code setup    digits: 6       # 6 or 8    period: 30      # seconds    algorithm: SHA1 # SHA1, SHA256, or SHA512

Duo Push example

mfa:  strategy: duo_push  duo_push:    poll_interval_ms: 1000   # how often to check (default: 1000)    timeout_ms: 120000       # give up after this many ms (default: 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 | browser | headless | session_cookie | oauth      api_token:        token_ref: env:BRIGHTSPACE_API_TOKEN    session:      cache_backend: memory        # memory | file | redis      preemptive_refresh_seconds: 300
output:  tz: America/Bogota               # IANA timezone; default: auto-detected from system  locale: es-419                   # en-US | es-419 | pt-BR | fr-CA; default: auto-detected  format: markdown                 # markdown (default) | plain  include_meta_footer: true
logging:  level: info                      # debug | info | warn | error
writes:  enabled: false  dry_run: false
# Optional — required when session.cache_backend: redisredis:  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:

Output: timezone and language

All tool responses are formatted in your configured timezone and language.

output:  tz: America/Bogota       # IANA name; default: auto-detected from system  locale: es-419           # en-US | es-419 | pt-BR | fr-CA; default: auto-detected  format: markdown         # markdown (default) | plain  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):

npm install ioredis

3. Start Redis and the server:

docker run -d -p 6379:6379 redis:7-alpinenpx 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   # set true to preview without mutating D2L

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.

Available tools

Read tools (always available)

Write tools (require --enable-writes)

MCP Resources

Four stable URIs for Brightspace content (readable by any MCP client via resources/read):

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:

TUI dashboard

brightspace-mcp tui            # launch full-screen terminal dashboardbrightspace-mcp tui --profile work  # use a specific profile

Full-screen interactive terminal UI (Ink + React). Six tabs navigated with Tab / → / ←:

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 enablednpx brightspace-mcp@latest tui                        Full-screen terminal dashboard (Ink TUI)npx brightspace-mcp@latest auth                       Re-authenticate and test the confignpx brightspace-mcp@latest record-auth                Open browser for manual login, capture session cookiesnpx brightspace-mcp@latest doctor                     End-to-end smoke test: config → auth → API → list_my_coursesnpx brightspace-mcp@latest profile list               List profiles (* marks the default)npx brightspace-mcp@latest profile use <name>         Switch the default profilenpx 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 runningnpx brightspace-mcp@latest config set <path> <value>  Edit a nested config valuenpx brightspace-mcp@latest cache clear                Clear memory + file/Redis cachenpx brightspace-mcp@latest cache clear --context <n>  Clear a specific cache contextnpx brightspace-mcp@latest upgrade                    Check npm and print the upgrade command

Docker

Standalone

docker pull ghcr.io/jhostinaleck/brightspace-mcp:latestdocker 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)

# Start server + Redisdocker compose --profile redis up
# Or standalone (in-memory cache)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