canvas-control
Allows interaction with Canvas LMS, providing tools for listing courses, searching/downloading files, syncing course files, checking grades, and submitting assignments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@canvas-control list my courses"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
canvas-control
canvas-control turns Canvas LMS into a fast, scriptable download pipeline and exposes it to AI assistants via MCP.
Download files from multiple Canvas content sources in one command
Sync course files like
git pull— skip unchanged, re-download on demandCheck grades across all courses from the terminal or export to CSV/JSON
Submit assignments from the terminal (file upload, text entry, URL)
Talk to Canvas through AI assistants (Claude Desktop, Cursor, Claude Code) — search files, download by name or type, sync courses, and set paths in natural language
Star History
Related MCP server: Canvas MCP Server
Table of contents
Why canvas-control
One command downloads from
files,assignments,discussions,pages, andmodules.Built for repeatable workflows: predictable output paths, machine-readable manifests, idempotent re-runs.
Guided mode (
download interactive) for beginners, fully scripted mode (download run) for power users.Grades accessible from the terminal: summaries, per-assignment breakdowns, CSV/JSON export.
MCP server lets AI assistants query courses, grades, assignments, and sync files with natural language.
Quick start
canvas-control uses uv for environment and dependency management.
Create and activate a virtual environment (Python 3.12+):
uv venv --python 3.12
source .venv/bin/activateInstall the project and dev dependencies:
uv pip install -e '.[dev]'Set your Canvas base URL once:
cvsctl config set-base-url https://your-school.instructure.comSet
CANVAS_TOKEN(see configuration docs) or letcvsctlprompt for it.Run the onboarding wizard to configure everything interactively, or jump straight to your first command:
# Guided setup (recommended for first-time users)
cvsctl onboard
# Or go straight to listing your courses
cvsctl courses listMCP server (AI assistants)
canvas-control includes an MCP (Model Context Protocol) server so you can interact with Canvas through AI assistants using natural language.
Available tools
Tool | Description |
| List enrolled courses (active or all) |
| Assignments due within a time window |
| Recent course announcements |
| Calendar events within a time window |
| Course syllabus content |
| Grade overview across courses |
| Per-assignment grade breakdown |
| List all files in a course (raw) |
| Search files by name, type, or folder — preview before downloading |
| Download a single file by ID |
| Download a batch of specific files to a local directory |
| Save a download path to config (global or per-course) |
| Mark assignment complete (submission or module completion flow) |
| Sync all course files to local disk; supports custom |
Natural language file downloads
Three new tools enable a conversational download workflow directly from Claude Desktop or Cursor:
**search_course_files** — search before you download. Filter by name substring, file extension, or folder path. The assistant shows you a preview of matching files so you can confirm before anything hits disk.
**download_selected_files** — download a batch of specific files (by Canvas file ID) to any local directory. Skips files that already exist, so it's safe to re-run. Returns a per-file status: downloaded, skipped, or failed.
**set_download_path** — persist a directory path to config so you don't have to specify it every time. Set a global default or a per-course path.
**sync_course_files** — now accepts an optional destination parameter, so you can tell the assistant exactly where to put everything without touching config first.
Example conversation:
You: Search for PDF files in my Biology course
Claude: Found 8 PDFs — Lecture 1.pdf, Lecture 2.pdf, Syllabus.pdf …
You: Download those to ~/Documents/Bio
Claude: Downloaded 7, skipped 1 (already exists). Saved to ~/Documents/Bio.
You: Save that as my default path for Biology
Claude: Saved ~/Documents/Bio as the download path for Biology (course 12345).Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"canvas": {
"command": "uv",
"args": ["--directory", "/path/to/canvas-control", "run", "cvsctl", "mcp", "serve"],
"env": {
"CANVAS_TOKEN": "your-token",
"CANVAS_BASE_URL": "https://your-school.instructure.com",
"CANVAS_TIMEZONE": "America/Los_Angeles"
}
}
}
}Cursor
Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:
{
"mcpServers": {
"canvas": {
"command": "uv",
"args": ["--directory", "/path/to/canvas-control", "run", "cvsctl", "mcp", "serve"],
"env": {
"CANVAS_TOKEN": "your-token",
"CANVAS_BASE_URL": "https://your-school.instructure.com",
"CANVAS_TIMEZONE": "America/Los_Angeles"
}
}
}
}Claude Code
claude mcp add canvas -- uv --directory /path/to/canvas-control run cvsctl mcp serveSet CANVAS_TOKEN, CANVAS_BASE_URL, and optionally CANVAS_TIMEZONE in your shell profile or .envrc.
Example prompts
Courses, grades, and assignments:
"What classes am I taking?"
"What assignments are due this week?"
"Show my grades for Biology"
"Are there any new announcements?"
"Mark Homework 2 complete"
Downloading files:
"Search for slides in my CS101 course"
"Download the lecture PDFs from my Biology course to ~/Documents/Bio"
"Save ~/Documents/Bio as my default download path for Biology"
"Sync all files from my Time Series course to ~/Documents/School"
"Re-download all files for Biology, overwriting existing ones"
CLI highlights
Download all files for a course:
cvsctl download run --course 12345View grades at a glance:
cvsctl grades summaryExport grades to CSV:
cvsctl grades export --detailedGuided interactive download:
cvsctl download interactiveSubmit an assignment:
cvsctl assignments submit --course 12345 --assignment "Homework 1" --file ./solution.pySee CLI Reference for the full command tree and all options.
Documentation
Configuration — token setup, download paths, per-course paths
CLI Reference — full command tree and behavior notes
Guides — workflows, grades, interactive mode, troubleshooting
Dev Testing
When changes are merged into the main branch, update your local clone and reinstall so the MCP server picks up the latest code.
Pull the latest changes:
git pull origin mainReinstall the package (picks up new dependencies or entry-point changes):
uv pip install -e '.[dev]'Run the test suite to verify nothing is broken:
uv run pytestRestart the MCP server in your AI client so it spawns a fresh process:
Claude Desktop: quit and relaunch the app
Cursor: open Settings → MCP and click the refresh/reconnect button
Claude Code: the server is spawned per-session; start a new session
Contributing
Create a branch for your change.
Implement focused changes and tests.
Run tests:
uv run pytestOptional live smoke test (requires real Canvas credentials):
export CANVAS_BASE_URL="https://your-school.instructure.com"
export CANVAS_TOKEN="your-token"
export CANVAS_TEST_COURSE_ID="12345"
uv run pytest -m liveOpen a PR with what changed, why, and test coverage.
Available Tools
14 toolscomplete_assignmentA
Complete or submit an assignment in Canvas.
When online submission is available and no submission payload is provided,
this tool responds with needs_input and tells the caller what is required.
If no supported submission path exists, it attempts module item completion.
Inputs: assignment_name, assignment_id, course_id, file_paths, +2 more. Returns: result
download_fileA
Download a single file from Canvas by file ID.
Args: file_id: The Canvas file ID. destination: Optional local path. Defaults to ~/Downloads/.
Inputs: file_id (required), destination. Returns: result
download_selected_filesA
Download a batch of specific Canvas files to a local directory.
Skips files that already exist at the destination (safe to re-run).
Args: file_ids: List of Canvas file IDs to download (from search_course_files). destination: Local directory path to save files to. ~ is expanded.
Inputs: file_ids (required), destination (required). Returns: result
get_announcementsA
Get recent announcements from Canvas courses.
Args: course_id: Optional course ID to filter. If omitted, gets from all active courses. limit: Maximum number of announcements to return (default 10).
Inputs: course_id, limit. Returns: result
get_calendar_eventsA
Get calendar events within a time window.
Args: course_id: Optional course ID to filter. If omitted, gets events from all contexts. days_ahead: Number of days ahead to look (default 14).
Inputs: course_id, days_ahead. Returns: result
get_grades_detailedB
Get detailed per-assignment grades for a specific course.
Args: course_id: The Canvas course ID.
Inputs: course_id (required). Returns: result
get_grades_summaryA
Get grade summary for enrolled courses.
Args: course_id: Optional course ID to filter. If omitted, shows all active courses.
Inputs: course_id. Returns: result
get_syllabusB
Get the syllabus for a specific course.
Args: course_id: The Canvas course ID.
Inputs: course_id (required). Returns: result
get_upcoming_assignmentsA
Get upcoming assignments that are due within a time window.
Args: course_id: Optional course ID to filter. If omitted, checks all active courses. days_ahead: Number of days ahead to look for due dates (default 14).
Inputs: course_id, days_ahead. Returns: result
list_course_filesC
List all files in a Canvas course.
Args: course_id: The Canvas course ID.
Inputs: course_id (required). Returns: result
list_coursesA
List Canvas courses. By default shows only active enrollments.
Args: include_all: If True, include concluded/past courses too.
Inputs: include_all. Returns: result
search_course_filesA
Search for files in a Canvas course by name, extension, or folder.
Use this as a preview step before downloading — show the user what would be downloaded and let them confirm.
Args: course_id: The Canvas course ID. query: Case-insensitive substring to match in file display name or filename. file_type: File extension to filter by (e.g. "pdf", "docx"). Leading dot is stripped. folder: Case-insensitive substring to match in the Canvas folder path.
Inputs: course_id (required), query, file_type, folder. Returns: result
set_download_pathA
Save a download path to the config file for future use.
Args: destination: Local directory path to persist. ~ is expanded. course_id: Optional course ID. If provided, saves a per-course path. If omitted, saves the global default download path.
Inputs: destination (required), course_id. Returns: result
sync_course_filesA
Sync (download) all files for a Canvas course to the local filesystem.
Behaves like "git pull" for course files — downloads new/changed files and skips unchanged ones. Set force=True to re-download everything.
Args: course_id: The Canvas course ID to sync. force: If True, overwrite existing files even if unchanged. sources: Content sources to include. Defaults to all (files, assignments, discussions, pages, modules). destination: Optional local directory path to save files to. ~ is expanded. Overrides the configured course path and default destination.
Inputs: course_id (required), force, sources, destination. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Tools are mostly distinct, but download_file and download_selected_files overlap in purpose; descriptions help clarify. Similarly, sync_course_files could be confused with bulk download. Overall, most tools have clear boundaries.
All tools follow verb_noun snake_case pattern consistently. Verbs are descriptive (get, list, download, complete, set, sync). No mixing of conventions.
14 tools is appropriate for a Canvas LMS integration. Each tool covers a key feature area without unnecessary duplication.
Covers core Canvas features: courses, files, assignments, grades, announcements, calendar, syllabus. Missing individual assignment details and submission file upload, but complete_assignment handles submission with guidance. Minor gaps exist but a typical workflow can be completed.
Maintenance
Related MCP Connectors
The Canva MCP server connects AI assistants (like Claude, ChatGPT, and Cursor) to Canva's API, enabling them to create and manage designs directly within chat conversations. Key capabilities include generating new designs from prompts, autofilling templates, searching and resizing existing designs, importing files from URLs, exporting designs as PDFs or images, and managing folders and comments without switching between tools.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Related MCP Servers
- AlicenseBqualityDmaintenanceA local MCP server for Canvas LMS that enables querying courses, assignments, grades, modules, and more from any MCP-compatible AI client.12MIT
- AlicenseNot gradedqualityDmaintenanceA remote MCP server for querying Canvas LMS courses, assignments, and grades. Enables natural language interaction with Canvas data via MCP clients like Claude Desktop.11 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables managing Canvas LMS courses, assignments, grades, modules, and more from MCP-compatible clients like Claude Desktop, Kiro, or Amazon Q Developer.MIT
- AlicenseNot gradedqualityDmaintenanceConnects Canvas LMS (and other school platforms) to AI agents, enabling them to monitor assignments, grades, announcements, and changes, then rank work, brief students, or build study plans via MCP tools.1MIT