canvas-mcp

本页保存的是公开项目资料快照，阅读过程不需要连接 GitHub。

canvas-mcp

图片：CI 图片：License: MIT 图片：Node.js 图片：MCP

English | 简体中文

A read-only Model Context Protocol server for Canvas LMS. Deploy it once, add it as a custom connector in Claude or ChatGPT, and ask questions about your courses in plain language:

What’s due this week, and which of it have I already submitted? What do I need on the final to keep an A in CS 225? Summarize the announcements from the last two weeks. Did the TA leave any comments on my last lab?

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.

Contents

• Features
• Tools
• How it works
• Quick start
• Connecting a client
• Configuration
• Security
• Limitations
• Development
• Contributing
• License

Features

• Every tool is read-only. No write endpoints are wrapped, and inbox threads and discussions are fetched without marking them as read.
• The tools are built around the questions students actually ask: deadlines across all courses, missing work, grade weights, feedback and syllabus policies.
• Output is compact. Canvas HTML becomes plain text, and responses keep only the fields a model needs.
• It runs remotely over Streamable HTTP, so it works in web and mobile clients, not only desktop apps.
• It’s stateless. Each request gets a fresh server instance, and nothing is cached or stored.
• Three runtime dependencies, no build step, no database.

Tools

Area	Tool	What it returns
Courses	list_courses	Active courses with IDs, codes and terms
	get_syllabus	Syllabus text
	get_front_page	Course home page text
	list_modules	Modules and the items inside each
	list_pages / get_page	Wiki pages and their contents
	list_course_staff	Instructors and TAs, with email when visible
	list_groups	Your project / lab groups
Coursework	get_upcoming	Everything due in the next N days, with submission status
	get_todo	Canvas To Do list
	get_missing	Past-due work you haven’t submitted
	list_assignments / get_assignment	Assignments, instructions, rubric, your score and feedback
	list_quizzes / get_quiz	Classic Quizzes, settings and your attempts
	get_calendar_events	Lectures, exams and office hours from the calendar
Grades	get_grades	Current and final score in every course
	get_grade_breakdown	Assignment groups, weights, drop rules and every score
Files	list_files / get_file	Course files; text-based files are returned inline
Communication	get_announcements	Recent announcements across courses
	list_discussions / get_discussion	Discussion topics and full reply threads
	list_inbox / get_inbox_message	Inbox conversations and messages
	get_recent_activity	Activity stream: new grades, comments, replies

Parameters and output fields for each tool are documented in docs/tools.md.

How it works

flowchart LR
    A[Claude / ChatGPT] -- "MCP over HTTPS/<MCP_SECRET>/mcp" --> B[canvas-mcp]
    B -- "GET /api/v1/...Bearer CANVAS_API_TOKEN" --> C[Canvas LMS]

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.

Quick start

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 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:////mcp

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

Connecting a client

Claude (claude.ai, desktop and mobile): open Settings → Connectors, choose Add custom connector, and paste the connector URL. Leave the OAuth fields empty.

ChatGPT: enable developer mode for connectors, create a new connector, paste the connector URL and choose No authentication.

Claude Code:

claude mcp add --transport http canvas https:////mcp

Any other MCP client that supports the Streamable HTTP transport can use the same URL.

Start a conversation with something like “List my Canvas courses” to confirm it works.

Configuration

Variable	Required	Description
CANVAS_BASE_URL	yes	Your Canvas instance, e.g. https://canvas.instructure.com or https://canvas..edu
CANVAS_API_TOKEN	yes	Personal access token from Canvas
MCP_SECRET	yes	Random string of at least 24 URL-safe characters (A–Z a–z 0–9 - _); becomes part of the connector URL
PORT	no	Port to listen on. Defaults to 8080; most platforms set it for you

The server validates all variables at startup and exits with a clear message if anything is missing.

Security

• The Canvas client only exposes GET helpers, so there is no code path that writes to Canvas.
• Requests without the correct secret get the same 404 as any unknown URL, and the secret is compared in constant time.
• 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.
• Nothing is cached or stored, and only errors are logged.

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.

See SECURITY.md for how to report a vulnerability.

Limitations

• Each deployment serves one user, since the server acts as whoever owns the token. Run a separate instance for each person.
• PDFs, slides and Office files aren’t parsed. get_file returns a temporary download link for them instead.
• New Quizzes appear in list_assignments, not list_quizzes, and the Canvas API never exposes quiz questions to students.
• Lists are capped at 500 items (5 pages of 100) per call, and long text at 20,000 characters.
• get_calendar_events without a course_id covers at most 10 courses, which is a Canvas API limit.

Development

git clone https://github.com/boyuchengz/canvas-mcp.git
cd canvas-mcp
npm install
cp .env.example .env   # fill in your values
npm run dev            # restarts on file changes
npm test

Inspect the running server interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP, URL: http://localhost:8080//mcp

Project structure

src/
├── server.js            Entry point: config, HTTP listener, graceful shutdown
├── app.js               Express app, secret check, MCP transport
├── config.js            Environment validation
├── canvas.js            Read-only Canvas REST client with pagination
├── text.js              HTML → plain text
└── tools/
    ├── courses.js       Courses, syllabus, modules, pages, staff, groups
    ├── coursework.js    Planner, to-do, assignments, quizzes, calendar
    ├── grades.js        Course totals and grade breakdown
    ├── files.js         File listing and content
    └── communication.js Announcements, discussions, inbox, activity
test/                    node:test suites (no network access needed)

Contributing

Bug reports, feature ideas and pull requests are welcome. Please read CONTRIBUTING.md first. New tools must stay read-only.

License

MIT © Boyucheng Zhang

This project is not affiliated with or endorsed by Instructure, Inc. Canvas is a trademark of Instructure, Inc.