canvas-mcp

A self hosted MCP server for Canvas LMS.

Connect ChatGPT, Claude, or another MCP client to your own Canvas account for courses, assignments, grades, files, discussions, submissions, teacher workflows, and more.

Deploy to Vercel · Run locally · Privacy · Security · Contributing

Why this exists

Canvas has a large API, but most AI clients cannot use it directly.

canvas-mcp gives an MCP client a controlled bridge to a Canvas account using a personal Canvas access token. It works locally over stdio or remotely over Streamable HTTP.

The project is intentionally self hosted. There is no required account database, no hosted user system, and no Canvas OAuth requirement for the normal setup.

Related MCP server: canvas-mcp

Highlights

Safety model

Drafting is not submitting.

Reading an assignment, solving it, drafting an answer, rewriting it, or reviewing it does not submit anything to Canvas.

Submission and other consequential tools are separately exposed as write tools and carry MCP annotations such as destructiveHint so capable hosts can show their native approval UI before execution.

Those annotations are not the authorization boundary. Canvas permissions and the configured write mode are still enforced by the server.

Write modes

Teacher mode also pseudonymizes known student identity fields before data reaches the model. See PRIVACY.md for the exact boundaries and limitations.

Deploy to Vercel

The fastest remote setup is a normal Vercel deployment.

Set these environment variables:

Your remote MCP endpoint is:

https://your-deployment.example/mcp

ChatGPT

ChatGPT can use the built in OAuth 2.1 compatibility flow. Canvas authentication itself still uses the private CANVAS_ACCESS_TOKEN stored on your deployment.

Add your /mcp URL in ChatGPT and use OAuth. When the authorization page opens, enter the same MCP_AUTH_TOKEN configured on the deployment.

Use these values if ChatGPT shows the advanced OAuth screen:

The DCR warning is expected because this project uses CIMD rather than Dynamic Client Registration.

Other remote MCP clients

Clients that support a bearer token can authenticate directly:

Authorization: Bearer YOUR_MCP_AUTH_TOKEN

Get a Canvas access token

Inside Canvas:

1. Open Account

2. Open Settings

3. Find Approved Integrations

4. Choose New Access Token

5. Create a token and copy it

Use the normal Canvas origin as CANVAS_BASE_URL.

https://school.instructure.com

Do not include page paths such as /profile/settings.

Treat the Canvas access token like a password.

Run locally

Requirements:

• Node.js 20 or newer

• npm

git clone https://github.com/caleb-mau/canvas-mcp.git
cd canvas-mcp
npm install
npm run setup

Optional browser based local setup:

npm run setup:web

Example stdio MCP configuration:

{
  "mcpServers": {
    "canvas": {
      "command": "npm",
      "args": ["run", "start:stdio", "--silent"],
      "cwd": "/absolute/path/to/canvas-mcp"
    }
  }
}

Module first courses

Some Canvas courses are organized primarily through Modules rather than the Assignments page. canvas-mcp treats modules as first class course content.

Module tools can:

• List modules in course order

• Get one module and its completion or lock state

• List every module item in order

• Get one module item with completion requirements and content details

• Resolve a module item into its underlying Canvas content

• Read an entire module end to end

• Find the previous and next item in the teacher's module sequence

• Mark supported module items read, done, or not done

canvas_get_module_item_content and canvas_read_module understand Canvas module item types such as pages, files, assignments, quizzes, discussions, subheaders, external URLs, and external tools.

For Canvas hosted content, the MCP follows the linked Canvas API object. That means a module page can return its actual page body, an assignment can include the current submission, and a file can return its Canvas metadata.

External URLs and external tools are returned as targets but are not automatically browsed.

Example requests include:

What do I need to do in Unit 4?
Read everything my teacher put in the Week 7 module.
What comes after this page in the module?
Which module items are still incomplete?

Module video downloads

Module reading never downloads video bytes automatically.

When module content contains a supported public video URL, module content results expose a video_urls list. This can detect common YouTube and Vimeo links as well as direct media URLs found in Canvas page or module content.

If the user explicitly asks for the video file, canvas_download_module_video:

1. Re-fetches the requested Canvas module item

2. Resolves its linked Canvas content

3. Verifies the selected video URL actually appears in that module item

4. Creates a short lived signed file link

5. Downloads or streams the media only when the client opens that link

YouTube and similar public video pages use yt-dlp when a direct MP4 is not available. The server does not pass Canvas credentials, cookies, browser sessions, or login data to yt-dlp, and it does not attempt to bypass DRM.

On Vercel Linux x64, canvas-mcp can bootstrap the pinned official yt-dlp standalone binary into ephemeral /tmp storage on the first explicit video request. The binary is SHA 256 verified before execution. Other hosts can provide an existing binary with YTDLP_BINARY_PATH.

Video download links are stateless HMAC signed URLs with a ten minute lifetime. No download database or media cache is required.

Environment options:

Only download media you are authorized to access and save. Site terms and copyright rules still apply.

File submissions

Hosted and local files use separate tools on purpose.

Hosted files

canvas_submit_file accepts a client supplied file reference. In ChatGPT, the tool uses:

_meta["openai/fileParams"] = ["file"]

That lets compatible clients hand canvas-mcp a file from Google Drive, another connector, a user upload, or a generated file without requiring provider specific code.

The runtime file object contains:

{
  "download_url": "https://temporary-file-url.example/...",
  "file_id": "file_...",
  "mime_type": "application/pdf",
  "file_name": "essay.pdf"
}

canvas-mcp securely downloads the bytes, performs Canvas's official file upload flow, then submits the Canvas file ID.

Remote file URLs must use HTTPS. Localhost and private network targets are rejected, redirects are revalidated, download size is limited, and Canvas credentials are never forwarded to the file source.

Local files

canvas_submit_local_file accepts a filesystem path and is intended for local stdio clients.

Teacher privacy

Teacher mode is designed for FERPA conscious workflows, not as a blanket claim of FERPA compliance.

Known student names, emails, login IDs, SIS IDs, avatar URLs, and raw Canvas user IDs are replaced or removed where recognized. Students are represented with stable course scoped references such as:

student_R7K4Q2M8PZ

The mapping is not stored in a database. It is derived with HMAC and resolved against the live Canvas roster only when an action needs the real Canvas user ID.

The default teacher roster also minimizes data. Grades and activity history are omitted unless explicitly requested.

Read PRIVACY.md before using real education records.

Architecture

flowchart LR
    Client["ChatGPT / Claude / MCP client"] -->|"OAuth or bearer token"| MCP["canvas-mcp"]
    MCP -->|"Canvas personal access token"| Canvas["Canvas LMS"]
    Files["Drive / uploads / generated files"] -->|"Hosted file reference"| Client

    MCP -.->|"No required student database"| Stateless["Stateless student identity mapping"]

Canvas remains the source of truth for courses, rosters, assignments, submissions, and grades.

Canvas API coverage

Dedicated tools cover the most common workflows. For endpoints that do not have a dedicated tool, canvas_api can call same origin Canvas REST endpoints directly.

Mutating raw API calls still obey the configured write mode and are advertised as consequential writes.

Security

The project includes controls for:

• Same origin Canvas credential forwarding

• HTTPS only hosted file downloads

• Private network and localhost SSRF blocking

• Redirect validation

• Remote file size limits

• No application payload logging by design

• Cache-Control: no-store on hosted MCP responses

• Teacher identity pseudonymization

• OAuth PKCE and resource binding

Read SECURITY.md for reporting and deployment guidance.

Development

npm install
npm test
npm run typecheck
npm run build

Please use fictional data in tests. Never commit real Canvas tokens or student records.

See CONTRIBUTING.md before opening a pull request.

Status

This project is still early and intentionally small. Expect Canvas edge cases and district specific behavior. Bug reports with sanitized reproduction details are welcome.

License

MIT. See LICENSE.