canvas-mcp

A Model Context Protocol server that gives AI agents structured access to Canvas LMS — coursework, deadlines, grades, submissions, discussions, and messages — over the official REST API.

Works with any Instructure-hosted Canvas instance. Built and validated against canvas.okstate.edu.

Contents

• Why the REST API

• Features

• Tools

• Installation

• Configuration

• Usage

• Write safety

• Development

• Security

• Contributing

• License

Why the REST API

Canvas exposes a stable, versioned API at /api/v1/. Wrapping it — rather than scraping the web UI — yields:

• Single-call actions instead of multi-page navigation.

• Resilience to UI redesigns; the API is versioned.

• Compact, structured JSON that doesn't flood an agent's context with rendered HTML.

• Simple auth via one bearer token.

Browser automation is reserved for things genuinely outside Canvas — embedded LTI tools such as zyBooks, Cengage, or Coursera quizzes, whose contents Canvas itself cannot see.

Features

• 11 workflow-oriented tools spanning the full student workflow, designed for agent ergonomics (human-readable names over opaque IDs, consolidated multi-step actions).

• Dry-run safety on every write — nothing is submitted, posted, or sent without an explicit confirm: true.

• Cross-course planner — one call returns everything due across all courses.

• Zero-config secrets — the server auto-loads a local .env, so no token ever appears on a command line or in client config.

• Tested — offline boot check in CI plus a live contract/regression suite.

Tools

Installation

Requirements: Node.js ≥ 22.

git clone https://github.com/tylergibbs1/canvas-mcp.git
cd canvas-mcp
npm install
npm run build

Configuration

Generate a token in Canvas: Account → Settings → "+ New Access Token". Treat it like a password.

cp .env.example .env   # then set CANVAS_TOKEN

The server reads .env automatically. Real environment variables take precedence, so you may also pass these inline if you prefer.

Usage

Claude Code

The server auto-loads .env, so no secret is needed on the command line:

claude mcp add --scope user canvas -- node /absolute/path/to/canvas-mcp/dist/index.js

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "canvas": {
      "command": "node",
      "args": ["/absolute/path/to/canvas-mcp/dist/index.js"],
      "env": {
        "CANVAS_BASE_URL": "https://your-school.instructure.com",
        "CANVAS_TOKEN": "your_token_here"
      }
    }
  }
}

Any MCP-compatible client works — point it at node dist/index.js with the two environment variables set.

Write safety

Every write tool defaults to a dry run: it validates inputs and returns a preview of exactly what would be sent, but performs no action. You must re-call with confirm: true to actually submit, post, or send. An accidental or hallucinated call cannot change anything in Canvas.

Development

npm run dev       # run from source with tsx
npm run build     # compile TypeScript to dist/
npm test          # offline: boot the server and verify all tools register (no token)
npm run eval      # live: contract/regression suite (requires a token)
npm run inspect   # interactive MCP Inspector (requires a token)

Evaluation

• eval/eval.mjs (npm run eval) asserts data-independent invariants against the live API — deadline ordering, valid status values, HTML stripping, cross-tool grade consistency, and that every write tool's confirm:false path returns a dry run and never executes.

• eval/tasks.md provides realistic agent task prompts (happy path, multi-step, write safety, scope boundary) for behavioral evaluation, each with "what good looks like."

Security

• Tokens are secrets. .env is git-ignored; never commit it. Anyone with your token can act as you in Canvas.

• Scoped to your account. The server can only do what your Canvas account can do.

• Revocation. Remove a token anytime in Canvas under Account → Settings → Approved Integrations.

• Tokens are sent only to your configured CANVAS_BASE_URL over HTTPS.

Contributing

Issues and pull requests are welcome. Please run npm run build and npm test before opening a PR; if you have a Canvas token available, npm run eval is encouraged.

License

MIT © Tyler Gibbs