npm package: @krishpkreame/canvas-mcp-server
Description: A read-only Model Context Protocol (MCP) server for Canvas LMS — safe for student use with no state-mutating operations
Author: Krish Patel
Latest version: 2.5.1

# Canvas MCP Server v2.5.0

> **Forked from [DMontgomery40/mcp-canvas-lms](https://github.com/DMontgomery40/mcp-canvas-lms)**
>
> This fork strips the server down to **26 read-only tools** for safe student use. All state-mutating operations have been removed — no assignments can be submitted, no profiles updated, no module items marked complete. Nothing in Canvas is ever modified.
>
> **Why this fork?** I'm a student at the University of Auckland (UoA) and wanted a Canvas MCP I could safely connect to Claude without any risk of accidental writes to my account. The upstream repo is a full-featured server for students, instructors, and admins — this fork is just the read side.

---

> A read-only Model Context Protocol (MCP) server for Canvas LMS — safe for student use with no state-mutating operations

## 🎯 Key Features

### 🎓 For Students
- **Course Management**: Access all courses, syllabi, and course materials
- **Assignment Tracking**: View assignments, check submission status, and track due dates
- **Announcements**: Read course announcements
- **Progress Tracking**: Monitor grades, module completion, and calendar events
- **Quizzes**: View quizzes and quiz details
- **File Access**: Browse and download course files and resources

### 🛠️ Technical Excellence
- **Read-Only by Design**: No mutating operations — safe to connect to any Canvas account
- **In-Memory Caching**: TTL-based response cache with LRU eviction (10m / 5m / 1m tiers) — up to 40x faster on repeated calls
- **Request Deduplication**: Concurrent calls for the same endpoint share a single HTTP request
- **Token Efficient**: Compact JSON serialization and lean tool descriptions save ~30-40% tokens in LLM context
- **Robust API**: Automatic retries, `per_page=100` pagination (10x fewer round-trips), comprehensive error handling
- **Type Safe**: Full TypeScript implementation with strict types
- **26 Tools**: Focused, read-only coverage of Canvas LMS

## Quick Start

### Option 1: Clone and run locally (recommended)

```bash
git clone https://github.com/KrishPatel1404/mcp-canvas-lms.git
cd mcp-canvas-lms
npm install && npm run build
```

Then add to your MCP client config (Claude Desktop, opencode, Cursor, etc.):

```json
{
  "mcpServers": {
    "canvas-lms": {
      "command": "node",
      "args": ["/path/to/mcp-canvas-lms/build/index.js"],
      "env": {
        "CANVAS_API_TOKEN": "your_token_here",
        "CANVAS_DOMAIN": "your_school.instructure.com"
      }
    }
  }
}
```

### Option 2: opencode

Add to `~/.config/opencode/opencode.json` (or a project-level `opencode.json`):

```json
{
  "mcp": {
    "canvas-lms": {
      "type": "local",
      "command": ["node", "/path/to/mcp-canvas-lms/build/index.js"],
      "environment": {
        "CANVAS_API_TOKEN": "your_token_here",
        "CANVAS_DOMAIN": "your_school.instructure.com"
      }
    }
  }
}
```

### Option 3: NPM (once published)

```bash
npm install -g @krishpkreame/canvas-mcp-server
```

```json
{
  "command": "canvas-mcp-server",
  "env": {
    "CANVAS_API_TOKEN": "your_token_here",
    "CANVAS_DOMAIN": "your_school.instructure.com"
  }
}
```

## Transport Modes

The server supports two explicit transport modes:

- `stdio` (default): best for Claude Desktop/Codex/Cursor local MCP wiring.
- `streamable-http`: best for local HTTP integrations and containerized workflows.

### Transport environment variables

```bash
# Required Canvas auth
CANVAS_API_TOKEN=your_token
CANVAS_DOMAIN=your_school.instructure.com

# Transport selection
MCP_TRANSPORT=stdio # or streamable-http

# Streamable HTTP settings
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3000
MCP_HTTP_PATH=/mcp
MCP_HTTP_STATEFUL=true
MCP_HTTP_JSON_RESPONSE=true
MCP_HTTP_ALLOWED_ORIGINS=
```

## Performance

All optimizations are built-in with zero configuration required.

| Optimization | Impact |
|---|---|
| **Response cache** (TTL: 10m / 5m / 1m) | Up to 40x latency reduction on repeated calls |
| **`per_page=100`** default | Up to 10x fewer HTTP round-trips for paginated endpoints |
| **Request deduplication** | Concurrent calls for the same data share a single request |
| **Compact JSON** | ~30-40% fewer tokens in LLM context window |
| **Lean tool descriptions** | ~500+ tokens saved per `tools/list` response |

### Cache TTL Tiers

| Tier | TTL | Endpoints |
|---|---|---|
| Long | 10 min | User profile, course list, dashboard cards, syllabus |
| Medium | 5 min | Assignments, modules, pages, files, folders, quizzes |
| Short | 1 min | Submissions, grades, calendar, notifications, announcements |

### Tuning

```bash
CANVAS_TIMEOUT=60000      # Request timeout in ms (default: 30000)
CANVAS_MAX_RETRIES=3      # Retry count for 429/5xx errors
CANVAS_RETRY_DELAY=1000   # Base retry delay in ms (exponential backoff)
```

## 🎓 Workflow Examples

### Check Today's Assignments
```
"What assignments do I have due this week?"
```
**Lists upcoming assignments with due dates, points, and submission status**

### Check Grades
```
"What's my current grade in Biology?"
```
**Shows current scores, grades, and assignment feedback**

### Read Announcements
```
"Any new announcements in my courses?"
```
**Lists recent course announcements**

### Track Progress
```
"What modules do I need to complete in Math 200?"
```
**Shows module completion status and next items to complete**

## Getting Canvas API Token

1. **Log into Canvas** → Account → Settings
2. **Scroll to "Approved Integrations"**
3. **Click "+ New Access Token"**
4. **Enter description**: "Claude MCP Integration"
5. **Copy the generated token** Save securely!

⚠️ A standard student token is all that's needed — no admin privileges required.

## Development

```bash
git clone https://github.com/KrishPatel1404/mcp-canvas-lms.git
cd mcp-canvas-lms
npm install

# Start development with hot reload
npm run dev:watch

# Code quality
npm run lint
npm run type-check
```

## 📚 Available Tools — 26 read-only tools

All tools are **read-only**. Nothing in Canvas is ever modified.

### System
| Tool | Description |
|------|-------------|
| `canvas_health_check` | Check API connectivity and confirm your token works |

### Courses
| Tool | Description |
|------|-------------|
| `canvas_list_courses` | List all enrolled courses |
| `canvas_get_course` | Get detailed info for a specific course |
| `canvas_get_syllabus` | Get the syllabus body for a course |
| `canvas_get_dashboard_cards` | Get dashboard course cards |

### Assignments & Submissions
| Tool | Description |
|------|-------------|
| `canvas_list_assignments` | List all assignments in a course |
| `canvas_get_assignment` | Get details for a specific assignment |
| `canvas_list_assignment_groups` | List assignment groups and weights |
| `canvas_get_submission` | View your submission for an assignment |
| `canvas_get_upcoming_assignments` | Get upcoming due dates across all courses |

### Grades & Calendar
| Tool | Description |
|------|-------------|
| `canvas_get_course_grades` | Get your current grade and scores for a course |
| `canvas_list_calendar_events` | List calendar events within a date range |

### Modules
| Tool | Description |
|------|-------------|
| `canvas_list_modules` | List all modules in a course |
| `canvas_get_module` | Get details for a specific module |
| `canvas_list_module_items` | List all items inside a module |
| `canvas_get_module_item` | Get details for a specific module item |

### Announcements & Notifications
| Tool | Description |
|------|-------------|
| `canvas_list_announcements` | List course announcements |
| `canvas_list_notifications` | List your activity stream notifications |

### Files & Pages
| Tool | Description |
|------|-------------|
| `canvas_list_files` | List files in a course or folder |
| `canvas_get_file` | Get details and download URL for a file |
| `canvas_list_folders` | List folders in a course |
| `canvas_list_pages` | List wiki pages in a course |
| `canvas_get_page` | Get the content of a specific page |

### Quizzes
| Tool | Description |
|------|-------------|
| `canvas_list_quizzes` | List all quizzes in a course |
| `canvas_get_quiz` | Get details for a specific quiz |

### User
| Tool | Description |
|------|-------------|
| `canvas_get_user_profile` | Get your Canvas profile information |

## 🌟 Example Claude Conversations

**Student**: *"What assignments do I have due this week?"*

**Claude**: *Let me check your upcoming assignments...*

[Claude uses `canvas_get_upcoming_assignments`]

---

**Student**: *"What's my current grade in Biology?"*

**Claude**: *Let me pull your grades for that course...*

[Claude uses `canvas_get_course_grades`]

---

**Student**: *"Show me the modules I need to complete in Math 200"*

**Claude**: *I'll list the modules and their completion status for you...*

[Claude uses `canvas_list_modules`, then `canvas_list_module_items`]

## 🔍 Troubleshooting

**Common Issues:**
- ❌ **401 Unauthorized**: Check your API token is correct and not expired
- ❌ **404 Not Found**: Verify course/assignment IDs and that you're enrolled in the course
- ❌ **403 Forbidden**: Some endpoints (e.g. rubrics) require instructor access — expected for students
- ❌ **Timeout**: Increase `CANVAS_TIMEOUT` in your `.env` or check network connectivity

**Debug Mode:**
```bash
export LOG_LEVEL=debug
npm start
```

## 🤝 Contributing

### Quick Contribution Setup
```bash
git clone https://github.com/KrishPatel1404/mcp-canvas-lms.git
cd mcp-canvas-lms
npm install
npm run dev:watch
# Make changes, add tests, submit PR
```

## 🙋 Support & Community

- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/KrishPatel1404/mcp-canvas-lms/issues)
- 💬 **Questions**: [GitHub Discussions](https://github.com/KrishPatel1404/mcp-canvas-lms/discussions)
- 📦 **Upstream**: [DMontgomery40/mcp-canvas-lms](https://github.com/DMontgomery40/mcp-canvas-lms)

## Appendix: MCP in Practice (Code Execution, Tool Scale, and Safety)

Last updated: 2026-03-16

### Why This Appendix Exists
MCP is still one of the most useful interoperability layers for agentic tooling. The tradeoff is that large MCP servers can expose dozens of tools, and naive tool-calling can flood context windows with tool schemas, call traces, and low-signal chatter.

In practice, larger tool surfaces only help when orchestration stays token-efficient and execution behavior is constrained.

### The Shift to Code Execution / Code Mode
Recent production workflows move orchestration out of conversational turns and into executable loops. This keeps context overhead lower, improves determinism, and makes runs auditable.

Core reading:
- [Cloudflare: Code Mode](https://blog.cloudflare.com/code-mode/)
- [Cloudflare: Code Execution with MCP](https://blog.cloudflare.com/code-execution-with-mcp/)
- [Anthropic: Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp)

### Recommended Setup for Power Users
For lower-noise, repeatable MCP usage, start with codemode-oriented routing:
- [codemode-mcp (jx-codes)](https://github.com/jx-codes/codemode-mcp)
- [UTCP](https://www.utcp.io)

Even with strong setup, model behavior can be hit-or-miss across providers and versions. Keep retries and deterministic fallbacks.

### Peter Steinberger Workflow Pattern
A high-leverage pattern is turning broad MCP tool surfaces into narrower CLI/task interfaces:
- [MCPorter](https://github.com/steipete/mcporter)
- [OpenClaw](https://github.com/steipete/openclaw)

### What Works Best With Which MCP Clients
- Claude Code / Codex / Cursor agent workflows: usually strong for direct MCP + code-execution loops.
- Thin hosted chat clients: often safer with wrapped CLIs/gateways instead of full raw tool exposure.
- High-tool-count servers: usually better when split into narrow task gateways.

This ecosystem changes quickly. If you are reading this now, parts of this section may already be out of date.

### Prompt Injection: Risks, Consequences, and Mitigations
Prompt injection remains an open problem for tool-using agents. It is manageable, but not solved.

Primary risks:
- Hidden instructions in retrieved content or tool output.
- Secret/token exfiltration through unintended calls.
- Unauthorized state changes in systems or data.

Mitigation baseline:
- Least-privilege credentials and scoped tokens.
- Destination/action allowlists and strict schema validation.
- Human confirmation for destructive operations.
- Sandboxed execution and resource limits.
- Structured logging and replayable execution traces.

Treat every tool output as untrusted input unless explicitly verified.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

<div align="center">
  <strong>Canvas MCP Server v2.5.0</strong><br>
  <em>A safe, read-only Canvas integration for students</em><br><br>
  
  ⭐ **Star this repo if it helps you!** ⭐
</div>