Canvas MCP Server

A read-only Model Context Protocol 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

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

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

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

Register with an MCP client (Claude Code shown):

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

Stack

Python 3.11+ · mcp · 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.