Canvas LMS (read-only)

canvas-readonly-mcp

Ask Claude what changed in your courses, and search every lecture slide. A read-only MCP server for Canvas LMS, built as a study assistant rather than a full Canvas API.

• Knows what changed: daily snapshots of your courses, so "what's new since yesterday?" is one call: new announcements, moved deadlines, new grades, edited pages, even which slides in a lecture PDF changed.
• Searches inside your files: full-text search over pages, assignments, announcements and the text of every linked PDF, slide deck and document, with the page or slide number. It finds files linked from pages and modules even when the Files tab is hidden.
• Read-only by design: it only ever sends GET requests to Canvas. It can't submit, post, grade or change anything, and it doesn't even mark discussions as read.
• Your token stays with you: one-click Claude Desktop extension (token in your system keychain), local stdio, or your own server for claude.ai. Nothing goes through a third party.

Works with any Canvas instance. Made for students; TAs and teachers can use it too (for reading, e.g. "needs grading" counts).

Not affiliated with or endorsed by Instructure. "Canvas" is a trademark of Instructure, Inc.

What you can ask

• "What changed in my courses since yesterday?"
• "What's due in the next two weeks, and what have I not submitted?"
• "Summarize the lab 2 instructions" (the server finds the PDF linked from the course and returns its text)
• "Which slides in lecture 5 changed since last week?"
• "Where did we cover dynamic programming?" (searches pages, announcements and the text of every linked PDF and slide deck)
• "How will lab 3 be graded, and what did I lose points on in lab 2?"

Tools

Quick start

1. Get a Canvas access token

In Canvas: Account → Settings → + New access token. Give it a purpose ("Claude") and preferably an expiry date.

You also need your Canvas address, e.g. https://canvas.yourschool.edu or https://yourschool.instructure.com.

2a. Claude Desktop: one-click extension (easiest)

1. Download canvas-readonly-mcp-<version>.mcpb from the latest release.
2. Open it (double-click, or drag it into Claude Desktop → Settings → Extensions) and click Install.
3. Enter your Canvas address and access token. The token is stored in your system keychain.

Nothing else to install: Claude Desktop runs the extension with its built-in Node.js.

2b. Local: Claude Code and other stdio clients

Requires Node.js 22.13 or newer.

Claude Code:

claude mcp add canvas \  -e CANVAS_BASE_URL=https://canvas.yourschool.edu \  -e CANVAS_TOKEN=your-token \  -- npx -y canvas-readonly-mcp

Claude Desktop without the extension: add this to claude_desktop_config.json (Settings → Developer → Edit Config):

{  "mcpServers": {    "canvas": {      "command": "npx",      "args": ["-y", "canvas-readonly-mcp"],      "env": {        "CANVAS_BASE_URL": "https://canvas.yourschool.edu",        "CANVAS_TOKEN": "your-token"      }    }  }}

In stdio mode, snapshots refresh shortly after the client starts the server, and in the background whenever they're older than SNAPSHOT_MAX_AGE_H (default 20h). Data is stored in your user data directory (~/Library/Application Support/canvas-readonly-mcp on macOS, ~/.local/share/canvas-readonly-mcp on Linux, %APPDATA%\canvas-readonly-mcp on Windows).

2c. Server: claude.ai custom connectors (HTTP)

claude.ai connects from the internet, so this needs a server with HTTPS.

mkdir canvas-mcp && cd canvas-mcpcurl -O https://raw.githubusercontent.com/rbrtlol/canvas-readonly-mcp/main/docker-compose.ymlcurl -o .env https://raw.githubusercontent.com/rbrtlol/canvas-readonly-mcp/main/.env.example# Fill in CANVAS_BASE_URL and CANVAS_TOKEN, then:sed -i "s/^MCP_SECRET=.*/MCP_SECRET=$(openssl rand -hex 32)/" .envchmod 600 .envdocker compose up -dcurl -s localhost:8787/healthz   # {"ok":true}

Put a reverse proxy with TLS in front of it: deploy/Caddyfile.example (automatic certificates) or deploy/nginx.conf.example. In claude.ai, add a custom connector with the URL

https://canvas-mcp.example.com/mcp/<MCP_SECRET>

and leave the OAuth fields empty. Clients that support headers can use https://…/mcp with Authorization: Bearer <MCP_SECRET> instead.

Without Docker: npx canvas-readonly-mcp --http --env-file .env.

Configuration

All settings are environment variables (or a file passed with --env-file).

How it works

Finding files. Many Canvas setups hide the files and pages lists from students. The server therefore uses those lists when your role may see them, and otherwise follows links from the front page, modules, syllabus, assignments and announcements. canvas_get_page shows file links inline as (file:<id>). Leftover $CANVAS_OBJECT_REFERENCE$ links from course copies are resolved where possible and otherwise marked as broken.

Reading files. canvas_read_file downloads the file (the token is only sent to Canvas itself, never to the storage host it redirects to) and extracts text in a separate worker thread with memory and time limits. Results are cached by file id and updated_at. Scanned PDFs without a text layer are reported as such (no OCR). Legacy .doc/.ppt aren't supported.

Snapshots and the change log. Once a day (and when stale), the server stores the state of each course on your Canvas dashboard in SQLite (star a course under Courses → All courses to add it, or set SNAPSHOT_COURSES): pages, modules, assignments (with your submission status and grade), announcements and discussions (with a teacher/TA flag), quizzes, calendar events, the syllabus, and file metadata with a per-page content hash for PDFs. Each item is normalized (HTML to text, volatile fields dropped) and hashed. Differences become change events with old → new values, short text diffs, and changed PDF page numbers. The first run is a silent baseline. Announcements with no posted_at (copied from an earlier course round) are flagged "unpublished/old". Items are only marked removed when every source that could link to them was read successfully, so a temporary error never produces false "removed" events.

Roles. Your role in each course comes from your enrollment. As a student, your submissions, grades and missing/late flags are tracked. As a TA or teacher, your own submissions are skipped, only staff discussion topics are tracked, and assignments show how many submissions need grading. Observer accounts work for course content, but the observed student's submissions aren't tracked.

Rate limits. The server watches Canvas's X-Rate-Limit-Remaining, backs off on 403 "Rate Limit Exceeded", 429 and 5xx responses, and limits how many requests run at once.

Security and privacy

• Treat the token like a password: it can read everything you can see in Canvas. The server never sends it anywhere except your Canvas.
• In HTTP mode the connector URL contains the secret: anyone with it can read your Canvas data (read-only). Wrong secrets get a plain 404. Rotate by changing MCP_SECRET.
• Course content (pages, announcements, file text) is written by other people and goes to the model as tool output. See SECURITY.md about prompt injection.
• Data stays on your machine/server: a SQLite database and an extracted-text cache. Delete DATA_DIR (or the Docker volumes) to remove it.
• No telemetry and no hosted service: see PRIVACY.md for what is read, stored and sent where.

Development

npm installnpm test             # unit + integration tests against a mock Canvasnpm run typechecknpm run buildCANVAS_BASE_URL=… CANVAS_TOKEN=… node dist/cli.js          # stdionode dist/cli.js --http --env-file .env                     # HTTPnpm run bundle       # build + pack the Claude Desktop extension (.mcpb)

The extension manifest is mcpb/manifest.json; its version is taken from package.json when packing. Update its tools list when adding or renaming a tool.

See CONTRIBUTING.md.

License

MIT