Blackboard Learn MCP Server
nitsuah/bb-mcp
API do Blackboard Learn para LLMs via MCP com autenticação e RBAC
Ver no GitHubServidor MCP standalone que expõe a API REST do Blackboard Learn para clientes LLM via HTTP ou stdio, com camada de autenticação OAuth2 e RBAC. Integração pronta para plataformas educacionais, permitindo acesso estruturado a cursos, notas, tarefas e anúncios.
Instalação
npx convez-ai nitsuah/bb-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar Blackboard Learn com Claude, Cursor ou agentes IA
- Automatizar consultas de notas, tarefas e anúncios via LLM
- Construir assistentes educacionais com acesso controlado por papel (RBAC)
Veredito

Solução bem arquitetada e production-ready com 91% cobertura de testes, zero vulnerabilidades críticas e CI/CD robusto. Ideal para instituições que precisam conectar Blackboard Learn a agentes de IA mantendo segurança e conformidade FERPA.
README
A tradução para o português deste README ainda está na fila.
blackboard-learn-mcp
A standalone Model Context Protocol server wrapping the Blackboard Learn REST API. Point any MCP-compatible client at it — Claude Desktop, Cursor, agent-board, or anything else — and get structured access to courses, grades, assignments, announcements, and more.
Why standalone?
The integration logic lives here, not in the client. Tools like agent-board, Claude Desktop, and Cursor all connect the same way. Build it once, use it everywhere. Blackboard's own team could point internal tooling at this server without touching any frontend code.
Architecture
┌─────────────────────────────────────────────────┐
│ Any MCP Client │
│ (Claude Desktop · Cursor · agent-board · ...) │
└──────────────────────┬──────────────────────────┘
│ MCP Protocol (HTTP or stdio)
▼
┌─────────────────────────────────────────────────┐
│ blackboard-learn-mcp (this repo) │
│ │
│ Auth layer → OAuth2, role gate, FERPA │
│ Tools (11) → student + instructor tools │
│ Metrics → Prometheus /metrics │
│ Audit log → structured JSON → stdout │
└──────────────────────┬──────────────────────────┘
│ REST API
▼
Blackboard Learn
(your instance or sandbox)
Quick start
cp .env.example .env # Fill in BB_CLIENT_ID, BB_CLIENT_SECRET, BB_BASE_URL
docker compose -f config/docker-compose.yml up -d
Development
All checks run via Docker — no local Node.js required.
# Run all tests (79 tests, TypeScript)
docker compose -f config/docker-compose.yml --profile test run --rm test
# Full quality gate: lint + coverage + audit + complexity
make docker-test
# Individual targets
make docker-lint # lint only
make docker-build # production image
Pre-commit hooks (type-check on commit, tests on push):
pip install pre-commit && pre-commit install && pre-commit install --hook-type pre-push
See .github/workflows/ci.yml for the full CI pipeline.
Makefile reference
make docker-up # Build and start the standalone bb-mcp container
make docker-logs # Follow container logs
make docker-doctor # Safe env readiness report from inside the container
make docker-probe # Validate Blackboard credentials + minimal API call
make docker-manifest # Print the provider manifest from the built image
make docker-tools # Print the published tool catalog from the built image
make docker-down # Stop the standalone stack
Docker (recommended)
cp .env.example .env
# Fill in BB_CLIENT_ID, BB_CLIENT_SECRET, BB_BASE_URL
docker compose -f config/docker-compose.yml up -d
Repo-local standalone commands:
make docker-up # Build and start the standalone bb-mcp container
make docker-logs # Follow container logs
make docker-doctor # Safe env readiness report from inside the container
make docker-probe # Validate Blackboard credentials + minimal API call
make docker-manifest # Print the provider manifest from the built image
make docker-tools # Print the published tool catalog from the built image
make docker-down # Stop the standalone stack
The standalone compose stack keeps the same Dockerfile path used by agent-board, but now adds a more confined runtime posture: read-only filesystem, dropped Linux capabilities, no-new-privileges, and a small /tmp tmpfs for Node runtime needs.
Server is live at http://localhost:3100.
| Endpoint | Description |
|---|---|
POST /mcp | MCP protocol entry point |
GET /health | Liveness probe |
GET /metrics | Prometheus text format |
GET /manifest | Provider contract with capabilities and tool manifest |
GET /oauth/authorize | Start the OAuth Authorization Code flow |
GET /oauth/callback | Complete OAuth code exchange and return a managed session |
GET /sse/search-course-materials | Dedicated SSE stream for incremental search_course_materials output |
cp .env.example .env
npm install
npm run dev # tsx watch — hot reload
stdio mode (Claude Desktop / Cursor)
npm run build
node dist/index.js --stdio
CLI inspection commands
# Show available runtime modes and inspection commands
node dist/index.js --help
# Print the provider manifest without starting the server
node dist/index.js --manifest
# List the published tools with role coverage
node dist/index.js --tools
# Emit a safe environment readiness report (no secrets printed)
node dist/index.js --doctor
# Validate Blackboard credentials and a minimal API call
node dist/index.js --probe
Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"blackboard-learn": {
"command": "node",
"args": ["/path/to/bb-mcp/dist/index.js", "--stdio"]
}
}
}
Configuration
Copy .env.example to .env and set:
| Variable | Required | Description |
|---|---|---|
BB_CLIENT_ID | ✅ | OAuth2 app client ID from developer.blackboard.com |
BB_CLIENT_SECRET | ✅ | OAuth2 app client secret |
BB_BASE_URL | ✅ | Base URL of your Blackboard Learn instance |
BB_OAUTH_REDIRECT_URI | — | Override the OAuth callback URL (defaults to PUBLIC_BASE_URL + /oauth/callback) |
BB_OAUTH_SCOPE | — | Optional scope string for the authorization code flow |
BB_OAUTH_AUTHORIZATION_PATH | — | Override Blackboard authorization endpoint path |
BB_OAUTH_TOKEN_PATH | — | Override Blackboard token endpoint path |
PORT | — | HTTP port (default 3100) |
LOG_LEVEL | — | info or debug (default info) |
METRICS_PUSH_URL | — | Prometheus push gateway URL (optional) |
RESTRICTED_TOOLS | — | Comma-separated tool names requiring FERPA auth |
Getting Blackboard credentials:
Register a REST API application at developer.blackboard.com. Use the free developer sandbox for testing — no live Blackboard instance required.
Authorization Code flow
bb-mcp now supports an operator-driven OAuth Authorization Code flow in addition to the existing client credentials probe path.
- Visit
GET /oauth/authorizeto start the flow. - Blackboard redirects back to
GET /oauth/callback. - bb-mcp validates the
state, performs PKCE-backed token exchange, and returns a managed session payload.
For non-browser operators, GET /oauth/authorize?format=json returns the authorization URL and redirect URI without issuing an HTTP redirect.
Tools
Every tool requires a caller_identity argument:
{
"caller_identity": {
"userId": "bbuser123",
"role": "student",
"clientApp": "agent-board"
}
}
For FERPA-restricted tools, add "ferpa_authorized": true — the calling application is responsible for asserting this only after real identity verification.
Student tools
| Tool | Description |
|---|---|
get_my_courses | Courses the caller is enrolled in |
get_upcoming_assignments | Assignments due within N days, sorted by due date |
get_my_grades | Grade breakdown across all courses or one course |
get_course_content | Course modules and materials, with optional keyword search |
get_assignment_feedback | Instructor comments, rubric scores, and annotations |
get_announcements | Course announcements |
create_assignment_submission | Submit an assignment attempt with optional student comments |
Instructor tools
| Tool | Description | FERPA required |
|---|---|---|
list_roster | Enrolled users for a course, including user IDs and usernames | — |
get_grades | Course-wide or user-scoped grade details, optionally filtered to one column | ✅ |
get_submission_status | Who submitted, who hasn't, timestamps | ✅ |
get_grade_distribution | Mean, median, std dev, A/B/C/D/F buckets | ✅ |
get_discussion_summary | Participant count and post excerpts for a thread | — |
get_at_risk_students | Students with low grades or many missing submissions | ✅ |
draft_announcement | AI-assisted announcement draft, optionally posted | — |
Shared tools
| Tool | Description |
|---|---|
search_course_materials | Full-text search across content in one or all courses |
MCP Resources
| URI | Description |
|---|---|
course://{courseId} | Full course object as JSON |
Identity & access control
The auth layer enforces three things before any Blackboard API call is made:
caller_identityis required on every tool call — the client asserts who is asking- Role gate — instructor-only tools reject
role: "student"callers - FERPA gate — tools that access protected student data require
ferpa_authorized: true
Every access attempt (granted or denied) is written to stdout as structured JSON:
{
"timestamp": "2026-03-24T10:00:00.000Z",
"event": "access.granted",
"tool": "get_my_grades",
"userId": "bbuser123",
"role": "student",
"courseId": null,
"clientApp": "agent-board",
"reason": null
}
This format is suitable for ingestion by any log aggregator (Datadog, CloudWatch, Loki, etc.).
Metrics
GET /metrics returns Prometheus-compatible text:
bb_mcp_tool_calls_total{tool="get_my_courses"} 42
bb_mcp_tool_errors_total{tool="get_my_grades"} 1
bb_mcp_tool_avg_duration_ms{tool="get_upcoming_assignments"} 238
Set METRICS_PUSH_URL to push to a Prometheus push gateway every 60 seconds.
agent-board integration
The server runs as a service in agent-board's Docker stack. The connector config lives at agent-board/config/connectors.json:
{
"name": "Blackboard Learn",
"mcp_server": "http://bb-mcp:3100",
"system_prompt": "You are a helpful study assistant...",
"safety_config": "strict",
"guided_prompts": [
"What do I have due this week?",
"How am I doing in my courses?",
"Summarize what I missed"
]
}
agent-board proxies MCP calls through POST /api/mcp/blackboard-learn/proxy, keeping credentials server-side.
Project structure
bb-mcp/
├── src/
│ ├── index.ts Entry point — HTTP + stdio transports
│ ├── config.ts Env validation
│ ├── bb-client.ts Blackboard REST API client (OAuth2 auto-refresh)
│ ├── auth.ts Role gate, FERPA guard, audit logging
│ ├── metrics.ts Prometheus metrics + withMetrics() wrapper
│ ├── types.ts Domain types (BbCourse, BbGrade, etc.)
│ └── tools/
│ ├── student.ts Student-facing tools
│ ├── instructor.ts Instructor-facing tools
│ └── shared.ts search_course_materials
├── Dockerfile Multi-stage build (node:22-slim)
├── docker-compose.yml Standalone stack (port 3100)
├── .env.example
├── package.json
└── tsconfig.json
Sandbox testing
No live Blackboard instance needed. Register a free developer account at developer.blackboard.com, create a REST API application, and use the provided sandbox URL as BB_BASE_URL. The sandbox exposes the full API surface with pre-populated test data.
License
MIT
Community Standards
Shared community policies are centralized in https://github.com/nitsuah/.github: