Brightspace

brightspace-mcp

📖 [Full documentation site →](https://jhostinaleck.github.io/brightspace-mcp/)

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)

| get_announcements | List course