# canvas-mcp

A **Model Context Protocol (MCP) server** that connects your **Canvas LMS** account to **Claude Desktop**. Ask Claude natural-language questions about your courses, assignments, grades, files, and more -- all powered by the Canvas REST API.

## Features

canvas-mcp exposes 15 tools to Claude Desktop:

| Tool | Description |
|------|-------------|
| `get_courses` | List all active enrolled courses |
| `get_assignments` | Assignments for a specific course with submission status |
| `get_all_assignments` | Every assignment across all courses, sorted by due date |
| `get_upcoming_assignments` | Assignments due in the next N days (default 7) |
| `get_calendar_events` | Upcoming calendar events (next 30 days) |
| `get_submission_status` | Per-assignment submission state (submitted / graded / unsubmitted) |
| `get_grades` | Current and final grade plus per-assignment scores |
| `get_course_modules` | Modules with item completion status |
| `get_announcements` | Recent announcements across all courses |
| `get_todo_items` | Your Canvas to-do list |
| `get_course_files` | List files uploaded to a course (PDFs, slides, etc.) |
| `get_course_pages` | List wiki/content pages in a course |
| `get_page_content` | Read the full text of a specific course page |
| `read_course_file` | Download and parse a file -- full PDF text extraction |
| `get_module_item_content` | Read content of all items in a module (lectures, notes, PDFs) |

## Project Structure

```
canvas-mcp/
├── src/
│   ├── index.ts          # MCP server entry point, tool definitions, and dispatch
│   ├── tools.ts          # Tool implementation functions
│   └── canvas-client.ts  # Canvas API client: HTTP helpers, pagination, type definitions
├── dist/                 # Compiled JavaScript (generated by build)
├── .env                  # Your credentials (not committed)
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md
```

## Prerequisites

- **Node.js** >= 18
- A **Canvas LMS** API access token

## Getting a Canvas API Token

1. Log in to your Canvas instance (e.g. `https://yourschool.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 MCP") and optionally set an expiry
6. Copy the token -- you will not be able to see it again

## Setup

### 1. Clone the repository

```bash
git clone https://github.com/YOUR_USERNAME/canvas-mcp.git
cd canvas-mcp
```

### 2. Install dependencies

```bash
npm install
```

### 3. Configure environment variables

Create a `.env` file in the project root:

```env
CANVAS_TOKEN=your_canvas_api_token_here
CANVAS_DOMAIN=yourschool.instructure.com
```

`CANVAS_DOMAIN` should be just the hostname (no `https://` prefix).

### 4. Build

```bash
npm run build
```

This compiles the TypeScript source to `dist/`.

### 5. Verify (optional)

```bash
node dist/index.js
```

The server communicates over stdio using the MCP protocol. It will start and wait for input. Press Ctrl+C to exit. If environment variables are missing, you will see a clear error immediately.

## Connecting to Claude Desktop

Add the server to your Claude Desktop configuration file.

### macOS

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "canvas": {
      "command": "node",
      "args": ["/absolute/path/to/canvas-mcp/dist/index.js"],
      "env": {
        "CANVAS_TOKEN": "your_canvas_token_here",
        "CANVAS_DOMAIN": "yourschool.instructure.com"
      }
    }
  }
}
```

### Windows

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "canvas": {
      "command": "node",
      "args": ["C:\\Users\\YOU\\path\\to\\canvas-mcp\\dist\\index.js"],
      "env": {
        "CANVAS_TOKEN": "your_canvas_token_here",
        "CANVAS_DOMAIN": "yourschool.instructure.com"
      }
    }
  }
}
```

Replace the path with the **absolute path** to your compiled `dist/index.js`. After saving, **restart Claude Desktop**.

## Example Prompts

Once connected, try these in Claude Desktop:

**Assignment planning**
- "What assignments do I have due this week?"
- "Show me everything due in the next 14 days."
- "Build me a study schedule for the next two weeks based on my due dates."

**Submission tracking**
- "Am I missing any submissions?"
- "Which assignments haven't I submitted yet in course 12345?"
- "Show me all overdue assignments."

**Grades**
- "What's my current grade in my Biology course?"
- "Show me all my graded assignments and scores."
- "Which course am I doing worst in?"

**Course content**
- "What courses am I enrolled in this semester?"
- "What was covered in this week's lectures for course 12345?"
- "Read the syllabus PDF from my math course."
- "What modules have I completed in course 12345?"

**Comprehensive**
- "Give me a full academic status report -- courses, grades, upcoming work, and missing submissions."
- "I have a free weekend. What should I prioritize based on upcoming deadlines and my current grades?"

## Development

```bash
# Run in dev mode without building (uses ts-node)
npm run dev

# Rebuild after making changes
npm run build
```

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `Missing required environment variables` | Check your `.env` file or the `env` block in `claude_desktop_config.json` |
| `Canvas API error 401` | Your token is invalid or expired -- generate a new one |
| `Canvas API error 403` | You do not have permission to access that resource |
| No active courses found | Your enrollment state may differ -- verify in Canvas directly |
| Claude does not see the server | Verify the absolute path in your config and restart Claude Desktop |

## License

This project does not currently include a license file.