# Canvas LMS MCP Server

An MCP (Model Context Protocol) server that connects Claude Code to your Canvas LMS account. Ask Claude about your courses, assignments, grades, and files — no manual downloading needed.

## What it does

This server exposes 13 tools that let Claude Code interact with your Canvas account:

| Tool | Description |
|------|-------------|
| `list_courses` | List all your enrolled courses |
| `get_course_modules` | Get the module structure for a course |
| `get_module_items` | Get items within a specific module |
| `get_page_content` | Read a Canvas page as clean text |
| `search_course_content` | Search across all pages in a course |
| `list_course_files` | List files in a course or folder |
| `download_file` | Download a file to your local disk |
| `get_assignments` | List assignments with due dates and status filters |
| `get_assignment_details` | Full assignment details with submission status |
| `get_syllabus` | Get the course syllabus |
| `get_announcements` | Get recent course announcements |
| `get_grades` | Get your grades and submission scores |
| `export_course_content` | Bulk download an entire course as a ZIP |

## Setup

### 1. Generate a Canvas Personal Access Token

1. Log into your Canvas instance (e.g. `https://uncch.instructure.com`)
2. Go to **Account** > **Settings**
3. Scroll to **Approved Integrations**
4. Click **+ New Access Token**
5. Give it a name (e.g. "Claude Code MCP") and click **Generate Token**
6. Copy the token — it looks like `7006~abc123...`

### 2. Install dependencies

```bash
cd /path/to/canvas-mcp
npm install
```

### 3. Configure in Claude Code

Add the server to your Claude Code MCP config. For **global** access (all projects), create or edit `~/.claude/.mcp.json`:

```json
{
  "mcpServers": {
    "canvas-lms": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/canvas-mcp/src/index.ts"],
      "env": {
        "CANVAS_DOMAIN": "your-school.instructure.com",
        "CANVAS_ACCESS_TOKEN": "7006~your-token-here",
        "CANVAS_DOWNLOAD_DIR": "/absolute/path/to/canvas-mcp/downloads"
      }
    }
  }
}
```

For **project-level** access, create `.mcp.json` in your project root with the same content.

### 4. Restart Claude Code

Restart Claude Code and run `/mcp` to verify the server is connected and all 13 tools appear.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `CANVAS_DOMAIN` | Yes | Your Canvas instance domain (e.g. `uncch.instructure.com`) |
| `CANVAS_ACCESS_TOKEN` | Yes | Personal access token from Canvas Settings |
| `CANVAS_DOWNLOAD_DIR` | No | Directory for downloaded files (defaults to `./downloads`) |

## Usage Examples

Once configured, just ask Claude naturally:

- "List my Canvas courses"
- "What are my grades in COMP 455?"
- "Show me the modules for course 104811"
- "Download the latest homework for my CS class"
- "What assignments do I have coming up?"
- "Get the syllabus for STOR 435"
- "Search my COMP 211 course for 'linked list'"
- "Export all content from my COMP 301 course"

## How it works

The server uses the [Canvas LMS REST API](https://canvas.instructure.com/doc/api/) with Bearer token authentication. It handles pagination, rate limiting, and converts Canvas HTML content to clean readable text for Claude.

Built with:
- `@modelcontextprotocol/sdk` — MCP protocol implementation
- `cheerio` — HTML to text conversion
- `adm-zip` — ZIP extraction for course exports
- `zod` — Input validation

## Project Structure

```
canvas-mcp/
├── src/
│   ├── index.ts              # Entry point, registers tools, stdio transport
│   ├── canvas-client.ts      # Canvas API client (auth, pagination, rate limits)
│   ├── html-to-text.ts       # HTML to clean text conversion
│   └── tools/
│       ├── courses.ts        # list_courses
│       ├── modules.ts        # get_course_modules, get_module_items
│       ├── pages.ts          # get_page_content, search_course_content
│       ├── files.ts          # list_course_files, download_file
│       ├── assignments.ts    # get_assignments, get_assignment_details
│       ├── syllabus.ts       # get_syllabus
│       ├── announcements.ts  # get_announcements
│       ├── grades.ts         # get_grades
│       └── export.ts         # export_course_content
├── package.json
└── tsconfig.json
```