_         _   _
  ___ __ _ _ ___ ____ _ __| |_ __ __| |_| |
 / __/ _` | ' \ V / _` (_-<  _/ _/ _|  _| |
 \___\__,_|_||_\_/\__,_/__/\__\__\__|\__|_|

What is this

canvasctl mirrors your Canvas courses — assignments, quizzes, modules, files, and announcements — into a plain-JSON vault at ~/canvas-vault/, then gives you fast terminal answers to "what's due today?", "what changed since yesterday?", and "export the next 60 days as a calendar." A built-in chat agent (canvasctl ask / canvasctl chat) uses your own Anthropic API key to answer natural-language questions by calling read-only tools over that vault. And an MCP server (canvasctl mcp) exposes the same operations to Claude Code and Claude Desktop, so you can ask Claude about your coursework from anywhere.

Everything runs on your machine. The only network calls it makes are to your own school's Canvas instance and — if you opt into the agent — directly to api.anthropic.com with your own key. It is read-focused by design: there is no assignment submission and no mutation of Canvas.

Quick start

# 1. Install (see alternatives below if you'd rather use pipx or a venv)
curl -fsSL https://raw.githubusercontent.com/vivekp-05/canvasctl/main/install.sh | sh

# 2. Onboard — asks for your Canvas URL + access token, optionally an Anthropic key
canvasctl setup

# 3. Pull your courses into the local vault, then ask away
canvasctl sync
canvasctl today
canvasctl ask "what's due this week?"

Install alternatives

pipx, straight from git (isolated, on your $PATH):

pipx install "canvasctl[agent,mcp] @ git+https://github.com/vivekp-05/canvasctl.git"

Drop the [agent,mcp] extras if you only want the core read-only CLI without the Claude chat agent or MCP server.

From source, with a virtualenv:

git clone https://github.com/vivekp-05/canvasctl.git
cd canvasctl
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[agent,mcp,dev]"
canvasctl --version

Features

Every read command supports --json for piping into jq, and --course <id|alias> to scope to one course.

The chat agent and MCP server are bring-your-own-key: nothing is proxied through anyone else. Your Anthropic key is read from ~/.config/canvasctl/config.json (written by canvasctl setup) or the ANTHROPIC_API_KEY environment variable.

Use it from Claude Code / Claude Desktop

canvasctl mcp speaks the Model Context Protocol over stdio, exposing your vault's read operations as tools.

Claude Code — register it in one line:

claude mcp add canvasctl -- canvasctl mcp

Claude Desktop — add an entry to the mcpServers block of your claude_desktop_config.json:

{
  "mcpServers": {
    "canvasctl": {
      "command": "canvasctl",
      "args": ["mcp"]
    }
  }
}

Then ask Claude things like "what canvasctl says is due this week?" or "summarize the latest announcements in my courses." See docs/mcp.md for the full tool list, setup details, and example prompts.

Layout of the local vault

~/canvas-vault/
├── state/
│   ├── config.json           # vault path, aliases, last_sync_at
│   ├── metadata/
│   │   ├── _courses/courses.json
│   │   └── <course_id>/{assignments,quizzes,modules,module_items,files,announcements}.json
│   └── logs/
│       ├── last_hashes.json  # for diffing between syncs
│       └── changes.jsonl     # append-only change-log
├── content/                  # downloaded files (canvasctl pull)
└── outputs/                  # generated artifacts (canvasctl ics)

The vault is plain JSON on disk — feel free to grep, jq, or back it up directly.

Your Canvas token and Anthropic key are not stored in the vault. They live in a separate credentials file at ~/.config/canvasctl/config.json (mode 600).

Security & privacy

• Bring your own keys (BYOK). You supply your own Canvas personal access token and your own Anthropic API key. Nothing is proxied through a third party.
• Treat your Canvas token like a password. A Canvas personal access token is a full-access student credential — anyone holding it can act as you across every course and setting your account can reach. Generate it under Account → Settings → New Access Token, give it a short expiry, and revoke it the moment you suspect exposure.
• Credentials live in one file, locked down. canvasctl setup writes your Canvas URL, token, and optional Anthropic key to ~/.config/canvasctl/config.json and sets its permissions to 600 (owner read/write only). It is never committed and never copied into the vault.
• Nothing leaves your machine except direct calls to Canvas and Anthropic. The only outbound traffic is to your school's Canvas host (to sync) and, if you use the agent, to api.anthropic.com with your own key. There is no telemetry and no middleman server.
• Read-focused by design. canvasctl only reads from Canvas. There is no assignment submission, no grade posting, and no mutation of any Canvas resource — the MCP server and chat agent expose read/local operations only.

For the full threat model, see docs/security.md.

Requirements

• Python 3.10 or newer. The core CLI runs on 3.10+; the ask/chat agent and the mcp server additionally require the optional anthropic and mcp packages (installed via the [agent] / [mcp] extras).
• A Canvas LMS account and a personal access token.
• An Anthropic API key, only if you want the ask / chat agent.

Development

git clone https://github.com/vivekp-05/canvasctl.git
cd canvasctl
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[agent,mcp,dev]"

# Run the test suite
pytest -q

Package layout:

canvasctl/
├── cli.py            # argparse + dispatch
├── client.py         # Canvas REST client (retry, backoff, pagination)
├── store.py          # vault layout + atomic JSON I/O + change log
├── diff.py           # by-id diffing
├── records.py        # normalize Canvas dicts -> due-date records
├── timeutil.py       # window parsing + safe datetime handling
├── formatting.py     # colors, tables, byte formatting
├── ops/              # operation registry shared by the CLI, agent, and MCP server
└── commands/         # one module per subcommand

The ops/ registry is the single source of truth for every Canvas operation: each op is defined once (name, description, JSON schema, handler, kind) and consumed by three surfaces — the argparse CLI, the MCP server, and the chat agent.

License

MIT © 2026 Vivek Patel.

Disclaimer

canvasctl is an independent, unofficial tool for use with Canvas LMS. It is not affiliated with, endorsed by, or sponsored by Instructure, Inc. "Canvas" and "Instructure" are trademarks of Instructure, Inc.