Canvas Connector

A free, MIT-licensed Canvas connector for AI assistants. Navigate courses, read assignments and documents, inspect feedback and grades, and prepare student actions through the Model Context Protocol (MCP). This independent project is not affiliated with or endorsed by Instructure or Canvas.

Status: development release. Local stdio and a hosted OAuth reference server are included. No public service or app-directory listing is claimed. See validation for what has actually been tested and capabilities for remaining Canvas app gaps.

Source and issues: Aadi-FTC-12868/canvas-connector. Setup and downloads: Built by Aadi.

Run locally

Requires Python 3.12 or later. From this repository:

python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock -e ./packages/canvas-py -e ./packages/canvas-mcp-v2 -e '.[dev,postgres]'

Put CANVAS_BASE_URL and CANVAS_API_TOKEN in a private environment file outside this repository, restrict it to your user, and point CANVAS_ENV_PATH to it. Use the full path to .venv/bin/canvas-connector as your MCP server command, with stdio as its argument. Writes are disabled unless you add --allow-writes. Never place a token in a chat or public configuration.

{
  "mcpServers": {
    "canvas": {
      "command": "/absolute/path/canvas-connector/.venv/bin/canvas-connector",
      "args": ["stdio"],
      "env": {"CANVAS_ENV_PATH": "/absolute/private/path/canvas.env"}
    }
  }
}

This JSON format applies to clients accepting mcpServers; Codex uses its own MCP configuration or codex mcp add. See the client guide.

Related MCP server: canvas-control

Install from GitHub

Install UV and your assistant's command-line app first. For Codex:

codex plugin marketplace add https://github.com/Aadi-FTC-12868/canvas-connector.git
codex plugin add canvas-connector-personal@built-by-aadi

For Claude Code:

claude plugin marketplace add https://github.com/Aadi-FTC-12868/canvas-connector.git
claude plugin install canvas-connector-personal@built-by-aadi

Then follow the setup skill for your own account. See the client guide for secure configuration and desktop options. A plugin installation does not establish Canvas authorization.

Install packages

The release includes a personal Claude Desktop .mcpb extension and a local plugin marketplace for Codex and Claude Code. These bundle the connector and companion skill; their README and the client guide explain setup. Downloads do not install a hosted connection or enable writes automatically.

python scripts/build_mcpb.py
python scripts/build_plugins.py

Host for multiple users

The server uses two separate OAuth flows: the assistant authenticates to this connector, and each student authorizes Canvas through their school's login. Canvas credentials are encrypted in persistent storage; assistant tokens are separate, revocable, scoped, and never forwarded to Canvas.

You need a public HTTPS origin and a Canvas OAuth developer key enabled by each supported institution. Asking other users for personal tokens is not the hosted onboarding flow. Follow deployment, then connect the HTTPS /mcp endpoint using the host app's custom connector setup. App directories and one-click install URLs require their own publication processes.

canvas-connector keygen
# Save the generated key privately as CONNECTOR_ENCRYPTION_KEY.
# Configure the remaining CONNECTOR_* variables described in .env.example.
canvas-connector serve --host 127.0.0.1 --port 8000

The bundled Docker configurations bind to loopback for a TLS reverse proxy. Use SQLite for workers on one host, or PostgreSQL for separate replicas. Refresh coordination, request limits, continuations, action claims, and receipts share the database. The CLI supports up to eight workers; production capacity has not been established. See the synthetic measurements for a reproducible starting point.

Design

• One student navigation flow: dashboard, course, section, item, linked material.

• Structured results with access state, source/freshness, bounded content, warnings, and continuation information.

• Explicit read/write MCP annotations and OAuth scopes. Host clients own their approval UI. Prepared actions preserve exact targets and contents.

• PDF, DOCX, PPTX, HTML, CSV, and text extraction with coverage and continuation.

• Google/Microsoft links get connector-aware handoff instructions; school access restrictions remain in effect.

• No instructor materials, account exports, or credentials in this repository.

The companion assistant skill is optional and portable. The connector works without a client-specific skill installation.

Develop

.venv/bin/python -m pytest
.venv/bin/python scripts/check_protocol.py
.venv/bin/python scripts/release_check.py

See security, source provenance, and contributing. Canvas is an Instructure product; this project is independent and is not endorsed by Instructure, OpenAI, or Anthropic.