# Canvas MCP Server

A Model Context Protocol (MCP) server providing read-only access to Canvas LMS for student workflows, with optional NotebookLM integration for study material organization.

## Features

- **45 Tools** covering Canvas LMS functionality
- **Read-only access** - Safe for student use
- **Smart caching** - Reduces API calls
- **Rate limiting** - Respects Canvas API limits (~3000 req/hour)
- **NotebookLM integration** - Upload course content for AI-powered study

## Quick Start

### 1. Install Dependencies

```bash
npm install
npm run build
```

### 2. Configure Environment

```bash
cp .env.example .env
# Edit .env with your Canvas credentials
```

Required settings:
- `CANVAS_BASE_URL` - Your Canvas instance URL
- `CANVAS_API_TOKEN` - Generate at Canvas > Account > Settings > New Access Token

### 3. Add to Claude Code

Add to your Claude Code MCP configuration (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "canvas": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/canvas-mcp-server",
      "env": {
        "CANVAS_BASE_URL": "https://your-school.instructure.com",
        "CANVAS_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

### 4. (Optional) Setup NotebookLM

For NotebookLM integration:

```bash
cd src/python-bridge
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium
```

Then use `notebooklm_auth_setup` tool for interactive Google login.

## Available Tools (45 total)

### Phase 1: Core (5 tools)
| Tool | Description |
|------|-------------|
| `canvas_course_list` | List enrolled courses |
| `canvas_course_get` | Get course details |
| `canvas_assignment_list` | List assignments (with bucket filtering) |
| `canvas_assignment_get` | Get assignment details |
| `canvas_get_my_submission` | Get your submission for an assignment |

### Phase 2: Content (16 tools)
| Tool | Description |
|------|-------------|
| `canvas_module_list` | List course modules |
| `canvas_module_get` | Get module details |
| `canvas_module_items` | List items in a module |
| `canvas_module_progress` | Get module completion progress |
| `canvas_file_list` | List files in a folder |
| `canvas_file_get` | Get file metadata |
| `canvas_file_search` | Search for files |
| `canvas_folder_list` | List folders |
| `canvas_file_download` | Download file content |
| `canvas_discussion_list` | List discussions |
| `canvas_discussion_get` | Get discussion with replies |
| `canvas_announcement_list` | List announcements |
| `canvas_planner_items` | Get planner items |
| `canvas_todo_list` | Get todo items |
| `canvas_upcoming_events` | Get upcoming events |
| `canvas_missing_submissions` | Get missing assignments |

### Phase 3: Assessment (8 tools)
| Tool | Description |
|------|-------------|
| `canvas_rubric_list` | List rubrics in a course |
| `canvas_rubric_get` | Get rubric details |
| `canvas_rubric_for_assignment` | Get rubric for an assignment |
| `canvas_quiz_list` | List quizzes |
| `canvas_quiz_get` | Get quiz details |
| `canvas_quiz_submission` | Get your quiz submission |
| `canvas_group_list` | List your groups |
| `canvas_group_members` | List group members |

### Phase 4: User (11 tools)
| Tool | Description |
|------|-------------|
| `canvas_bookmark_list` | List your bookmarks |
| `canvas_bookmark_create` | Create a bookmark |
| `canvas_bookmark_delete` | Delete a bookmark |
| `canvas_inbox_list` | List inbox messages |
| `canvas_inbox_get` | Get conversation details |
| `canvas_inbox_unread_count` | Get unread message count |
| `canvas_notification_list` | List notifications |
| `canvas_dashboard` | Comprehensive dashboard view |
| `canvas_profile` | Get your profile |
| `canvas_grades_overview` | Get grades across courses |
| `canvas_cache_status` | View/clear cache |

### Phase 5: NotebookLM (5 tools)
| Tool | Description |
|------|-------------|
| `notebooklm_auth_check` | Check Google auth status |
| `notebooklm_auth_setup` | Interactive Google login |
| `notebooklm_list_notebooks` | List NotebookLM notebooks |
| `notebooklm_upload_sources` | Upload sources to notebook |
| `notebooklm_prepare_content` | Convert/split files for upload |

## Authentication

### Canvas API (Primary)
- **API Token**: Required for all API calls
- Generate at: Canvas > Account > Settings > New Access Token
- Provides access to your enrolled courses, assignments, grades, etc.

### Cookies (Secondary, Optional)
- Only needed if file downloads return 403 errors
- Export browser cookies using extensions like "Get cookies.txt"
- Set `CANVAS_COOKIES_FILE` in your environment

### NotebookLM (Interactive)
- Uses Playwright browser automation (no public API exists)
- Run `notebooklm_auth_setup` once to save Google session
- Session persists in `src/python-bridge/state.json`

## Architecture

```
canvas-mcp-server/
├── src/
│   ├── core/
│   │   ├── auth.ts        # Token + cookie authentication
│   │   ├── cache.ts       # Memory cache with TTL
│   │   ├── client.ts      # Canvas API client
│   │   ├── pagination.ts  # Link header parsing
│   │   └── rate-limiter.ts # Token bucket rate limiter
│   ├── tools/
│   │   ├── courses.ts     # Course tools
│   │   ├── assignments.ts # Assignment tools
│   │   ├── modules.ts     # Module tools
│   │   ├── files.ts       # File tools
│   │   ├── discussions.ts # Discussion tools
│   │   ├── planner.ts     # Planner tools
│   │   ├── rubrics.ts     # Rubric tools
│   │   ├── quizzes.ts     # Quiz tools
│   │   ├── groups.ts      # Group tools
│   │   ├── bookmarks.ts   # Bookmark tools
│   │   ├── communication.ts # Inbox/notification tools
│   │   ├── dashboard.ts   # Dashboard tools
│   │   └── notebooklm.ts  # NotebookLM tools
│   ├── python-bridge/
│   │   ├── notebooklm_auth.py   # Google auth management
│   │   ├── notebooklm_upload.py # Source upload automation
│   │   └── requirements.txt     # Python dependencies
│   ├── types/
│   │   └── canvas.ts      # TypeScript types
│   ├── server.ts          # MCP server
│   └── index.ts           # Entry point
├── .env.example           # Environment template
├── mcp.json               # MCP configuration
└── package.json
```

## Rate Limits

Canvas API allows ~3000 requests per hour. This server implements:
- Token bucket rate limiter (0.8 req/sec default)
- Smart caching (5-30 min TTL per resource type)
- Automatic retry with backoff on 429 responses

## License

MIT