# Canvas LMS MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that gives an
MCP client (Claude Desktop, Claude Code, or anything else that speaks MCP)
read-only access to your [Canvas LMS](https://www.instructure.com/canvas) account.

It answers two questions:

- **"What am I taking and how am I doing?"** — active courses with current grades.
- **"What do I still owe and when is it due?"** — outstanding assignments with due dates.

Communication uses the standard **stdio** transport, so the client launches the
server as a subprocess. Nothing is written to stdout except MCP traffic.

## Requirements

- Node.js 18.17 or newer (the server uses the built-in `fetch`)
- A Canvas personal access token

## Install

```bash
cd canvas-mcp-server
npm install
```

## Configuration

Both variables are required; the server exits with a clear message if either is missing.

| Variable | Description | Example |
| --- | --- | --- |
| `CANVAS_API_URL` | Your Canvas instance root. A trailing `/` or `/api/v1` is fine — it gets normalized. | `https://asu.instructure.com` |
| `CANVAS_ACCESS_TOKEN` | A Canvas personal access token. | `7~AbCdEf...` |

### Getting a Canvas access token

1. Log in to Canvas.
2. Go to **Account → Settings**.
3. Under **Approved Integrations**, click **+ New Access Token**.
4. Give it a purpose and (optionally) an expiry date, then click **Generate Token**.
5. Copy the token immediately — Canvas shows it only once.

The token carries your full Canvas privileges. Keep it out of version control,
and revoke it from the same settings page if it ever leaks.

## Connecting a client

Add the server to your MCP client config, pointing at the absolute path of
`src/index.js`:

```json
{
  "mcpServers": {
    "canvas": {
      "command": "node",
      "args": ["/absolute/path/to/canvas-mcp-server/src/index.js"],
      "env": {
        "CANVAS_API_URL": "https://asu.instructure.com",
        "CANVAS_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}
```

- **Claude Desktop** — `claude_desktop_config.json`
  (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`).
- **Claude Code** — `claude mcp add canvas --env CANVAS_API_URL=... --env CANVAS_ACCESS_TOKEN=... -- node /absolute/path/to/canvas-mcp-server/src/index.js`

Restart the client after editing the config.

## Tools

### `list_courses_and_grades`

Every course you are actively enrolled in as a student, with its current grade.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `include_all_terms` | boolean | `false` | Also include active enrollments from terms that have already ended. |

Canvas reports grades twice when your institution uses grading periods: once for
the period in progress and once for the whole course. The `grades.scope` field
says which one you are looking at:

- `current_grading_period` — the score covers the grading period in progress, and
  `course_total_score` / `course_total_grade` carry the whole-course numbers.
- `course_total` — the institution does not use grading periods, so the score is
  the course total.
- `unavailable` — Canvas returned no enrollment with grade data.

Within either scope, `current_*` ignores work that has not been graded yet, while
`final_*` counts ungraded work as a zero.

```jsonc
{
  "courses": [
    {
      "id": "101",
      "name": "Full Stack Web Development",
      "course_code": "GIT-411",
      "term": "Fall 2026",
      "term_start": "2026-08-20T00:00:00Z",
      "term_end": "2026-12-18T00:00:00Z",
      "enrollment_state": "active",
      "grades": {
        "current_score": 88.0,
        "current_grade": "B+",
        "final_score": 80.5,
        "final_grade": "B-",
        "scope": "current_grading_period",
        "grading_period_title": "Fall Term",
        "course_total_score": 91.4,
        "course_total_grade": "A-"
      },
      "html_url": "https://asu.instructure.com/courses/101"
    }
  ],
  "course_count": 1,
  "retrieved_at": "2026-09-01T12:00:00.000Z"
}
```

### `list_upcoming_assignments`

Assignments across your active courses that are still outstanding, sorted by due
date, soonest first.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `days_ahead` | integer 1–365, or `null` | `14` | How far ahead to look. `null` removes the upper bound. |
| `include_overdue` | boolean | `true` | Include past-due work that was never turned in. |
| `include_undated` | boolean | `false` | Include outstanding work with no due date. |
| `course_ids` | string[] | all active courses | Restrict to specific Canvas course IDs. |

An assignment counts as outstanding when it is published, gradable, and **not**
submitted, graded, or excused. Concretely, these are filtered out:

- anything with a submission timestamp
- submissions in `submitted`, `pending_review`, or `graded` state
- excused assignments
- assignments that already carry a score or grade (manual or on-paper entry)
- `not_graded` assignments (attendance placeholders and the like)
- unpublished assignments

```jsonc
{
  "assignments": [
    {
      "id": "9004",
      "name": "Missed lab writeup",
      "course_id": "101",
      "course_name": "Full Stack Web Development",
      "due_at": "2026-08-28T06:59:00.000Z",
      "days_until_due": -4.2,
      "overdue": true,
      "points_possible": 25,
      "submission_types": ["online_upload"],
      "submission_state": "unsubmitted",
      "missing": true,
      "locked": false,
      "unlock_at": null,
      "lock_at": null,
      "html_url": "https://asu.instructure.com/courses/101/assignments/9004"
    }
  ],
  "assignment_count": 1,
  "courses_checked": 2,
  "window": {
    "from": "2026-09-01T12:00:00.000Z",
    "to": "2026-09-15T12:00:00.000Z",
    "include_overdue": true,
    "include_undated": false
  },
  "errors": [],
  "retrieved_at": "2026-09-01T12:00:00.000Z"
}
```

If one course cannot be read — concluded, restricted, or otherwise erroring — it
is listed in `errors` and the remaining courses still return results.

## Notes on behavior

- **Pagination.** Canvas paginates every collection via the `Link` header. The
  client follows `rel="next"` at 100 records per page, capped at 20 pages per
  endpoint so a bad response cannot loop forever.
- **Concurrency.** Assignments are fetched from at most 5 courses at a time to
  stay clear of Canvas rate limits.
- **Current term.** By default only courses whose term has not ended are
  returned. Canvas's default term has no end date and is always included.
- **Errors.** Canvas failures come back as MCP tool errors carrying the status
  code and Canvas's own message, with a hint for the common cases (401 → bad
  token, 404 → wrong URL).
- **Read-only.** Both tools are annotated `readOnlyHint`. The server issues only
  `GET` requests and never modifies your Canvas data.

## Development

```bash
npm test    # 36 tests: API client, grade logic, filtering, and an end-to-end MCP round trip
```

The suite uses a `fetch` stand-in with recorded Canvas payloads, so no network or
real token is needed. All fixture dates are relative to the moment the tests run.

```
src/
  index.js        MCP server: tool definitions, schemas, stdio wiring
  canvas.js       Canvas REST client: auth, pagination, error mapping
  courses.js      Active-course and grade normalization
  assignments.js  Outstanding-assignment filtering and due-date windows
```

## License

MIT