Brightspace

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   # 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 wizard
npx brightspace-mcp@latest serve   # run the server

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     # 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: redis
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:

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-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   # 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 dashboard
brightspace-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 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)

# Start server + Redis
docker 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