# canvas-parent-mcp

[![CI](https://github.com/chrischall/canvas-parent-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/chrischall/canvas-parent-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/canvas-parent-mcp)](https://www.npmjs.com/package/canvas-parent-mcp)
[![license](https://img.shields.io/npm/l/canvas-parent-mcp)](LICENSE)

MCP server for Canvas LMS (Instructure), scoped for parent observers and student self-access. Targets `https://cms.instructure.com` by default but works against any Canvas instance.

Mirrors the read-only parent-portal scope of sibling [`infinitecampus-mcp`](https://github.com/chrischall/infinitecampus-mcp). Users interact via the `canvas_*` tool prefix.

## Tools

18 tools across profile, observees, courses, assignments, submissions, grades, calendar, planner, announcements, conversations, discussions, and files.

| Domain | Tools |
|---|---|
| Profile | `canvas_get_profile` |
| Observees | `canvas_list_observees` |
| Courses | `canvas_list_courses`, `canvas_get_course` |
| Assignments | `canvas_list_assignments`, `canvas_list_missing_submissions` |
| Submissions | `canvas_get_submission`, `canvas_list_recent_submissions` (default 14d window) |
| Grades | `canvas_list_enrollments` |
| Calendar | `canvas_list_calendar_events`, `canvas_list_upcoming_events` |
| Planner | `canvas_list_planner_items` |
| Announcements | `canvas_list_announcements` |
| Conversations | `canvas_list_conversations`, `canvas_get_conversation` |
| Discussions | `canvas_list_discussion_topics` |
| Files | `canvas_list_course_files`, `canvas_download_file` |

Tools that the harness will gate as write/IO operations: `canvas_download_file`.

### Planner: child names and a brief view

`canvas_list_planner_items` takes a child by name. At start the server lists your observees once (bounded to 5 s) and publishes their display names as the `observeeId` enum; the tool accepts either a name (any case) or a Canvas user id (`self`, a numeric id, or a `sis_user_id:`-style reference — including a child linked after the server started), and an unknown name is refused with the list of known ones. If the listing fails or you observe nobody, `observeeId` is published as a plain string and ids pass through as before. Two children with the same display name are listed as `Name (id)`.

`view: "brief"` returns one line per planner item, at most 120 characters (cut as a whole, title first): `title — <ISO date or "no date"> — <submitted|not submitted|missing>`. Items with nothing to submit (planner notes, pages, events) carry their kind as the status (`planner note`, `wiki page`, …). Titles are written by teachers, so the lines come back inside the untrusted-data envelope, `{"untrusted_content":true,"note":"…","data":["…"]}`; an empty planner is `data: ["-- none"]`, and a title that itself starts with `-- ` or `\` is escaped with one leading `\` so it never reads as a note. The default (`view: "full"`) is Canvas's payload, unchanged.

### Context-group hints

Every tool except `canvas_healthcheck` carries a `_meta.mint` hint for hosts that group tools by context (mcp-host's context groups): `domain: "school"` plus an `intent` — `whats-due` for the planner and missing submissions, `whats-new` for announcements, `whats-on` for the calendar tools, `lookup` for the other reads, `other` for the download. The planner (`whats-due`) and announcements (`whats-new`) are marked `canonical`; the planner also names its subject argument (`observeeId`) and range (`startDate`/`endDate`). Hosts that do not read `_meta` see nothing different.

`canvas_download_file` only fetches `/files/…` URLs on your `CANVAS_BASE_URL` host (https), so your Canvas credential is never sent anywhere else, and it only writes inside a download directory: `CANVAS_OUTPUT_DIR` if set, otherwise `~/Downloads`. A relative `destinationPath` is resolved against that directory. It never writes through a symlink at the destination, and new files are created owner-only (0600).

On a **hosted** deployment (mcp-host) the server's disk is not reachable from your session, so `canvas_download_file` writes nothing to disk: it reads the file (up to 100 MiB) and returns a signed download link that expires after an hour. An image under 10 MiB is shown inline instead. `destinationPath` is ignored there. A hosted server without a blob store returns files up to 10 MiB inline and refuses larger ones. On a local install, `destinationPath` is now optional; leave it out and the file is saved under its own name in the download directory, never overwriting an existing file.

## Configuration

Set `CANVAS_BASE_URL` plus one of four auth modes. `canvas-parent-mcp` tries them in priority order:

1. **`CANVAS_TOKEN`** → personal access token
2. **`CANVAS_CLIENT_ID` + `CANVAS_CLIENT_SECRET` + `CANVAS_REFRESH_TOKEN`** → OAuth
3. **`CANVAS_USERNAME` + `CANVAS_PASSWORD`** → session-scrape (direct Canvas accounts only)
4. **fetchproxy fallback** → no env vars needed; reads `canvas_session` + `pseudonym_credentials` cookies from your signed-in Canvas tab via the [ContextMint Bridge](https://github.com/nullnet-app/contextmint-bridge/releases) browser extension

If none succeed, you get an error that names every escape hatch.

### Mode A — fetchproxy fallback (recommended, zero config)

```
CANVAS_BASE_URL=https://cms.instructure.com
```

Install the ContextMint Bridge browser extension from its [releases page](https://github.com/nullnet-app/contextmint-bridge/releases) (Chrome: download the chrome zip, unzip it, and load it unpacked at `chrome://extensions` with Developer mode on — there is no Chrome Web Store listing yet; Safari: not available yet — it will ship inside the ContextMint app, which has no public download yet, so use Chrome for now), sign into your Canvas instance, and the MCP reads your session cookies from the browser on the first request and again whenever Canvas answers 401 (the session expired). In between, Canvas API calls go directly from Node — the extension is **not** in the request hot path, but it must stay reachable (browser running, extension installed) for the MCP to renew the session. Works with any auth flow (SSO/SAML/2FA included) because Canvas itself handled the sign-in.

> **Where the extension comes from.** ContextMint Bridge is the fetchproxy browser extension under its new name, from the same maintainer — fetchproxy's own README ([Extension](https://github.com/chrischall/fetchproxy#extension)) points to it. Its source is public at [nullnet-app/contextmint-bridge](https://github.com/nullnet-app/contextmint-bridge): build it yourself (`npm run build`, per its README), or check a release zip against the `.sha256` file published beside it:
>
> ```bash
> shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256
> ```

Multiple districts? Declared domain `instructure.com` matches every `*.instructure.com` host, so you only pair the extension once. The MCP uses whichever district you set in `CANVAS_BASE_URL`.

Set `CANVAS_DISABLE_FETCHPROXY=1` to opt out (missing creds become a hard error — useful in headless CI).

### Mode B — username/password (legacy session-scrape)

```
CANVAS_BASE_URL=https://cms.instructure.com
CANVAS_USERNAME=me@example.com
CANVAS_PASSWORD=your-canvas-password
CANVAS_NAME=cms                # optional, defaults to host portion of base URL
```

**Direct Canvas accounts only** — won't work with SAML/Google/Microsoft SSO or 2FA. Brittle (breaks on every Canvas login-page restyling). Prefer fetchproxy if your tab is already signed in. Treat `.env` like a password file.

### Advanced alternatives

<details>
<summary><b>Personal access token</b> — simplest if your admin allows it</summary>

```
CANVAS_BASE_URL=https://cms.instructure.com
CANVAS_TOKEN=your-personal-access-token
```

Generate via Canvas → Account → Settings → "+ New Access Token". Most institutions have disabled this for non-admins.
</details>

<details>
<summary><b>OAuth via mobile QR code</b> — bootstrapped from the mobile-app login flow</summary>

```
CANVAS_BASE_URL=https://cms.instructure.com
CANVAS_CLIENT_ID=...
CANVAS_CLIENT_SECRET=...
CANVAS_REFRESH_TOKEN=...
```

If your account uses SSO and you can't use fetchproxy (e.g. headless server), mint OAuth credentials by reusing the Canvas mobile-app QR-login flow — see [Bootstrapping OAuth via the mobile QR code](#bootstrapping-oauth-via-the-mobile-qr-code) below.
</details>

**Precedence when multiple are set:** `CANVAS_TOKEN` > username/password > OAuth > fetchproxy.

See `.env.example`.

### Session cache

In username/password and OAuth modes the signed-in session is cached between runs, so a restart does not log in (or spend a refresh-token exchange) again. The cache file — `$MCP_DATA_DIR/.canvas-parent-mcp/session.json` by default, or `CANVAS_SESSION_FILE` — holds the live `canvas_session` + `pseudonym_credentials` cookies or the OAuth access token **in plaintext**. It is created owner-only (0600, in a 0700 directory), and only the credential binding is stored as a salted digest; your username, password and refresh token are never written to it. Token and fetchproxy modes never write the cache.

Backup and sync tools that run as you can still copy that file. On a shared or backed-up machine, set `CANVAS_SESSION_CACHE=false` to keep the session in memory only (each start then re-authenticates).

### Bootstrapping OAuth via the mobile QR code

If your Canvas admin has disabled personal-access-token creation (some institutions restrict tokens to "the mobile app only") AND your account uses SSO so username/password can't auth, you can mint OAuth credentials by going through the same QR-login flow that the official Canvas mobile apps use:

1. In Canvas web, open **Account → QR for Mobile Login** — Canvas shows a QR that's valid for 10 minutes.
2. Decode the QR with any QR reader. The result is a URL on `sso.canvaslms.com` like `https://sso.canvaslms.com/canvas/login?domain=...&code=...`.
3. Run the bundled helper:

   ```
   npx canvas-parent-mcp-qr-login "<decoded-qr-url>" >> .env
   ```

   It hits Canvas's public `mobile_verify.json` endpoint to fetch the mobile client_id/client_secret, exchanges the QR's one-time code for an access+refresh token pair, and prints `CANVAS_BASE_URL` / `CANVAS_CLIENT_ID` / `CANVAS_CLIENT_SECRET` / `CANVAS_REFRESH_TOKEN` to stdout. The refresh token is sensitive — treat it like a password.

This reuses the same SSO + OAuth endpoints the official Canvas Student/Parent apps use; from Canvas's perspective the resulting session looks like a mobile-app session. Use it only against accounts you legitimately control.

## Upgrading

### next release

`canvas_download_file` now works on hosted deployments:

- `destinationPath` is optional (it was required). Local calls that pass it behave exactly as before and return the same `{path, bytes, contentType}`.
- Calls without `destinationPath`, and every call on a hosted server, return a delivery result instead: `{via, fileName, mimeType, url?, expiresAt?, path?, bytes, contentType, note?}`. `via` is `image` (inline image block), `resource` (inline bytes), `link` (signed `url` valid until `expiresAt`) or `disk` (`path`). An inline image or resource is returned as a content block before that JSON.
- On a hosted server `destinationPath` is ignored and the `note` says so.

## Status

Unofficial — not affiliated with Instructure. AI-maintained.

## Acknowledgement of Terms

By using this MCP server, you acknowledge and agree to the following:

**1. This server accesses your own Canvas account via the official Canvas REST API.** Auth happens via your own personal access token, issued by your institution. It does not — and cannot — access anyone else's enrollments, grades, or messages.

**2. [Instructure's Canvas API Policy](https://www.instructure.com/policies/canvas-api-policy) governs your use of this server**, in addition to your institution's own acceptable-use policy. The clauses most relevant here:

> You may not use our APIs on behalf of any third-party… You may not use or access our APIs for competitive purposes… You may not interfere with our APIs, our systems, or other users… You may not circumvent any contractual usage limits.

On rate limits: *"limits are enforced per user access token… with dynamic throttling."* On data: *"Any user information retrieved through the API—including course enrollments, grades, and profile information—should be considered and treated as private information."*

You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server.

**3. Personal, observer/student/parent use only.** This project is not affiliated with, endorsed by, sponsored by, or in partnership with Instructure, Inc. or any school district. It is a personal automation tool for an authenticated Canvas user (typically a parent observer) to read their own (or their student's) enrollments, assignments, grades, and announcements. Do not use it to bulk-extract a district's course content, redistribute student data, or train AI models on student records.

**4. FERPA + your institution's AUP apply.** Student educational records are protected under the federal Family Educational Rights and Privacy Act (FERPA). Even though your token grants you lawful access, **how you store, redistribute, or feed that data into LLMs is regulated**. Treat any output (grades, assignments, comments, conversations) as confidential student data. Your institution's acceptable-use policy may add further restrictions on automated access — check before automating.

**5. Your token is yours alone.** **Do not commit `CANVAS_API_TOKEN` to git**, do not paste it in shared chats, and rotate it if it's ever exposed. A leaked token grants full Canvas access scoped to your user.

**6. You accept full responsibility** for any consequences of using this server in connection with your Canvas account — rate limiting (dynamic throttling kicks in well below documented limits when Canvas is under load), token revocation, account warnings, institution-admin investigations, or any enforcement action. If Instructure or your institution objects to your use, stop using this server.

This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede Instructure's actual Canvas API Policy or your institution's policies.