# Canvas MCP Server

A read-only [Model Context Protocol](https://modelcontextprotocol.io) server that gives an AI assistant full structured access to a Canvas LMS account — courses, assignments, grades, deadlines, files, rubrics, and submission feedback.

Instead of opening Canvas and clicking through six courses to figure out what's due, you ask: *"what's due this week and what am I behind on?"* and get an answer grounded in live data.

---

## The problem

Canvas holds everything a student needs, spread across a UI that requires a lot of navigation to answer simple cross-course questions. "What's due in the next two weeks?" means visiting every course individually. There's an API, but it's awkward in ways that make naive integrations break:

- Array parameters require bracket notation (`include[]=total_scores`), silently ignored otherwise
- Pagination is driven entirely by `Link` headers — page-number guessing skips and duplicates records
- Rate limits are enforced by a leaky-bucket quota exposed in response headers
- Every text field is HTML, not plain text — unusable in a model context without cleaning
- Enrollments span all past semesters, so "my courses" needs term-aware filtering

This server absorbs that complexity and exposes 23 clean tools.

## Design decisions

**Two-phase loading.** List endpoints return lightweight representations; full content is fetched on demand. Pulling every assignment description across six courses wastes an enormous amount of context for a question like "what's due Friday." List calls stay cheap, detail calls are explicit.

**Link-header pagination.** `paginate()` is an async generator that follows `Link: rel="next"` until exhausted or a caller-supplied limit is hit, yielding items individually so callers can stop early without over-fetching.

**Rate-limit awareness, not just retry.** The client reads `X-Rate-Limit-Remaining` and pre-emptively backs off when the quota drops below 50, in addition to exponential backoff on 429s. Reacting only to 429s means you've already been throttled.

**Current-semester detection.** `_is_current_course()` filters enrollments by term dates so tools operate on the active semester without the user passing IDs around.

**HTML stripping at the boundary.** Canvas returns HTML in every description, announcement, and discussion body. It's converted to plain text before reaching the model — script and style blocks removed, `<br>` mapped to newlines.

**Singleton HTTP client.** One `httpx.AsyncClient` with connection pooling for the process lifetime, rather than a new connection per tool call.

**Read-only by design.** No tool mutates Canvas state. An LLM cannot submit an assignment, post to a discussion, or alter a grade — the blast radius of a bad generation is zero.

## Tools

**Core** — `get_my_courses`, `get_todo`, `get_all_upcoming(days)`, `get_all_grades`

**Course content** — `get_course`, `get_assignments`, `get_assignment`, `get_announcements`, `get_announcement`, `get_discussions`, `get_discussion`, `get_quizzes`, `get_quiz`, `get_calendar_events`, `get_rubrics`, `get_rubric`

**Files & modules** — `get_files`, `get_file`, `get_modules`, `get_module_items`, `get_page`

**Submissions** — `get_submission` (includes instructor feedback and rubric assessment)

**Aggregator** — `get_full_course_context` (entire course in one call, for deep questions)

## Setup

```bash
uv sync
cp .env.example .env    # then add your token
```

Generate a token at **Canvas → Account → Settings → New Access Token**.

```env
CANVAS_TOKEN=your_canvas_api_token_here
CANVAS_BASE_URL=https://your-institution.instructure.com
```

Register with an MCP client (Claude Code shown):

```bash
claude mcp add canvas -- uv --directory /path/to/canvas-mcp run server.py
```

## Stack

Python 3.11+ · [`mcp`](https://github.com/modelcontextprotocol/python-sdk) · `httpx` (async) · `python-dotenv` · typed dataclass models throughout

## Notes

Your access token carries your full Canvas privileges. It lives in `.env`, which is gitignored — don't commit it, and revoke it from Canvas settings if it's ever exposed.

Built against the Canvas API as deployed by Northeastern University. Institutions can disable endpoints, so tool availability may vary.