Skip to content
Back to search

canvas-mcp

Read-only MCP server that connects Claude, ChatGPT and other AI assistants to Canvas LMS.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/boyuchengz--canvas-mcp/badge.svg)](/listings/boyuchengz--canvas-mcp)

HTML

<a href="/listings/boyuchengz--canvas-mcp"><img src="/api/listings/boyuchengz--canvas-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Create a Canvas access token

In Canvas, open **Account → Settings**, scroll to **Approved Integrations**, and click **+ New Access Token**. Give it a purpose (e.g. "canvas-mcp") and an expiry date, then copy the token. Canvas only shows it once.

> Some institutions restrict personal access tokens. Check your school's acceptable-use policy before deploying.

2. Generate a connector secret

node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"

3. Deploy

The server runs anywhere Node.js 20+ can accept HTTPS traffic. [Railway](https://railway.com) is the quickest option:

npm i -g @railway/cli
railway login
railway init
railway up

Then, in the Railway dashboard:

1. **Variables**: add `CANVAS_BASE_URL`, `CANVAS_API_TOKEN` and `MCP_SECRET`. 2. **Settings → Networking**: click **Generate Domain**.

Your connector URL is:

https://<your-domain>/<MCP_SECRET>/mcp

Render, Fly.io, a VPS and local setups are covered in [docs/deployment.md](docs/deployment.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 208 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # canvas-mcp
  2. [![CI](https://github.com/boyuchengz/canvas-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/boyuchengz/canvas-mcp/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  4. ![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)
  5. ![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-6E56CF)
  6. English | [简体中文](README.zh-CN.md)
  7. A **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server for [Canvas LMS](https://www.instructure.com/canvas).
  8. Deploy it once, add it as a custom connector in Claude or ChatGPT, and ask questions about your courses in plain language:
  9. > *What's due this week, and which of it have I already submitted?*
  10. > *What do I need on the final to keep an A in CS 225?*
  11. > *Summarize the announcements from the last two weeks.*
  12. > *Did the TA leave any comments on my last lab?*
  13. Every one of the 26 tools issues `GET` requests only. The server cannot submit, post, delete or mark anything as read, so even a leaked connector URL only exposes what you could already see.
  14. ## Contents
  15. - [Features](#features)
  16. - [Tools](#tools)
  17. - [How it works](#how-it-works)
  18. - [Quick start](#quick-start)
  19. - [Connecting a client](#connecting-a-client)
  20. - [Configuration](#configuration)
  21. - [Security](#security)
  22. - [Limitations](#limitations)
  23. - [Development](#development)
  24. - [Contributing](#contributing)
  25. - [License](#license)
  26. ## Features
  27. - Every tool is read-only. No write endpoints are wrapped, and inbox threads and discussions are fetched without marking them as read.
  28. - The tools are built around the questions students actually ask: deadlines across all courses, missing work, grade weights, feedback and syllabus policies.
  29. - Output is compact. Canvas HTML becomes plain text, and responses keep only the fields a model needs.
  30. - It runs remotely over Streamable HTTP, so it works in web and mobile clients, not only desktop apps.
  31. - It's stateless. Each request gets a fresh server instance, and nothing is cached or stored.
  32. - Three runtime dependencies, no build step, no database.
  33. ## Tools
  34. | Area | Tool | What it returns |
  35. | --- | --- | --- |
  36. | Courses | `list_courses` | Active courses with IDs, codes and terms |
  37. | | `get_syllabus` | Syllabus text |
  38. | | `get_front_page` | Course home page text |
  39. | | `list_modules` | Modules and the items inside each |
  40. | | `list_pages` / `get_page` | Wiki pages and their contents |
  41. | | `list_course_staff` | Instructors and TAs, with email when visible |
  42. | | `list_groups` | Your project / lab groups |
  43. | Coursework | `get_upcoming` | Everything due in the next *N* days, with submission status |
  44. | | `get_todo` | Canvas To Do list |
  45. | | `get_missing` | Past-due work you haven't submitted |
  46. | | `list_assignments` / `get_assignment` | Assignments, instructions, rubric, your score and feedback |
  47. | | `list_quizzes` / `get_quiz` | Classic Quizzes, settings and your attempts |
  48. | | `get_calendar_events` | Lectures, exams and office hours from the calendar |
  49. | Grades | `get_grades` | Current and final score in every course |
  50. | | `get_grade_breakdown` | Assignment groups, weights, drop rules and every score |
  51. | Files | `list_files` / `get_file` | Course files; text-based files are returned inline |
  52. | Communication | `get_announcements` | Recent announcements across courses |
  53. | | `list_discussions` / `get_discussion` | Discussion topics and full reply threads |
  54. | | `list_inbox` / `get_inbox_message` | Inbox conversations and messages |
  55. | | `get_recent_activity` | Activity stream: new grades, comments, replies |
  56. Parameters and output fields for each tool are documented in [docs/tools.md](docs/tools.md).
  57. ## How it works
  58. ```mermaid
  59. flowchart LR
  60. A[Claude / ChatGPT] -- "MCP over HTTPS<br/>/&lt;MCP_SECRET&gt;/mcp" --> B[canvas-mcp]
  61. B -- "GET /api/v1/...<br/>Bearer CANVAS_API_TOKEN" --> C[Canvas LMS]
  62. ```
  63. The AI client calls the server at a URL that contains a long random secret. The server checks the secret in constant time, translates the tool call into one or more Canvas REST API `GET` requests using your personal access token, follows pagination, and returns a trimmed JSON result. The Canvas token never leaves the server.
  64. ## Quick start
  65. ### 1. Create a Canvas access token
  66. In Canvas, open **Account → Settings**, scroll to **Approved Integrations**, and click **+ New Access Token**. Give it a purpose (e.g. "canvas-mcp") and an expiry date, then copy the token. Canvas only shows it once.
  67. > Some institutions restrict personal access tokens. Check your school's acceptable-use policy before deploying.
  68. ### 2. Generate a connector secret
  69. ```bash
  70. node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"
  71. ```
  72. ### 3. Deploy
  73. The server runs anywhere Node.js 20+ can accept HTTPS traffic. [Railway](https://railway.com) is the quickest option:
  74. ```bash
  75. npm i -g @railway/cli
  76. railway login
  77. railway init
  78. railway up
  79. ```
  80. Then, in the Railway dashboard:
  81. 1. **Variables**: add `CANVAS_BASE_URL`, `CANVAS_API_TOKEN` and `MCP_SECRET`.
  82. 2. **Settings → Networking**: click **Generate Domain**.
  83. Your connector URL is:
  84. ```
  85. https://<your-domain>/<MCP_SECRET>/mcp
  86. ```
  87. Render, Fly.io, a VPS and local setups are covered in [docs/deployment.md](docs/deployment.md).
  88. ## Connecting a client
  89. **Claude** (claude.ai, desktop and mobile): open **Settings → Connectors**, choose **Add custom connector**, and paste the connector URL. Leave the OAuth fields empty.
  90. **ChatGPT**: enable developer mode for connectors, create a new connector, paste the connector URL and choose **No authentication**.
  91. **Claude Code**:
  92. ```bash
  93. claude mcp add --transport http canvas https://<your-domain>/<MCP_SECRET>/mcp
  94. ```
  95. **Any other MCP client** that supports the Streamable HTTP transport can use the same URL.
  96. Start a conversation with something like *"List my Canvas courses"* to confirm it works.
  97. ## Configuration
  98. | Variable | Required | Description |
  99. | --- | --- | --- |
  100. | `CANVAS_BASE_URL` | yes | Your Canvas instance, e.g. `https://canvas.instructure.com` or `https://canvas.<school>.edu` |
  101. | `CANVAS_API_TOKEN` | yes | Personal access token from Canvas |
  102. | `MCP_SECRET` | yes | Random string of at least 24 URL-safe characters (`A–Z a–z 0–9 - _`); becomes part of the connector URL |
  103. | `PORT` | no | Port to listen on. Defaults to `8080`; most platforms set it for you |
  104. The server validates all variables at startup and exits with a clear message if anything is missing.
  105. ## Security
  106. - The Canvas client only exposes `GET` helpers, so there is no code path that writes to Canvas.
  107. - Requests without the correct secret get the same `404` as any unknown URL, and the secret is compared in constant time.
  108. - The Canvas token is only sent to `CANVAS_BASE_URL`. Pagination links to any other host are ignored, and file downloads use Canvas's pre-signed URLs without the token.
  109. - Nothing is cached or stored, and only errors are logged.
  110. Treat the connector URL like a password: anyone who has it can read your Canvas data. If it leaks, change `MCP_SECRET` and redeploy. If your Canvas token leaks, delete it under **Approved Integrations**.
  111. See [SECURITY.md](SECURITY.md) for how to report a vulnerability.
  112. ## Limitations
  113. - Each deployment serves one user, since the server acts as whoever owns the token. Run a separate instance for each person.
  114. - PDFs, slides and Office files aren't parsed. `get_file` returns a temporary download link for them instead.
  115. - New Quizzes appear in `list_assignments`, not `list_quizzes`, and the Canvas API never exposes quiz questions to students.
  116. - Lists are capped at 500 items (5 pages of 100) per call, and long text at 20,000 characters.
  117. - `get_calendar_events` without a `course_id` covers at most 10 courses, which is a Canvas API limit.
  118. ## Development
  119. ```bash
  120. git clone https://github.com/boyuchengz/canvas-mcp.git
  121. cd canvas-mcp
  122. npm install
  123. cp .env.example .env # fill in your values
  124. npm run dev # restarts on file changes
  125. npm test
  126. ```
  127. Inspect the running server interactively with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
  128. ```bash
  129. npx @modelcontextprotocol/inspector
  130. # Transport: Streamable HTTP, URL: http://localhost:8080/<MCP_SECRET>/mcp
  131. ```
  132. ### Project structure
  133. ```
  134. src/
  135. ├── server.js Entry point: config, HTTP listener, graceful shutdown
  136. ├── app.js Express app, secret check, MCP transport
  137. ├── config.js Environment validation
  138. ├── canvas.js Read-only Canvas REST client with pagination
  139. ├── text.js HTML → plain text
  140. └── tools/
  141. ├── courses.js Courses, syllabus, modules, pages, staff, groups
  142. ├── coursework.js Planner, to-do, assignments, quizzes, calendar
  143. ├── grades.js Course totals and grade breakdown
  144. ├── files.js File listing and content
  145. └── communication.js Announcements, discussions, inbox, activity
  146. test/ node:test suites (no network access needed)
  147. ```
  148. ## Contributing
  149. Bug reports, feature ideas and pull requests are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) first. New tools must stay read-only.
  150. ## License
  151. [MIT](LICENSE) © Boyucheng Zhang
  152. This project is not affiliated with or endorsed by Instructure, Inc. Canvas is a trademark of Instructure, Inc.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.