npm package: @owen-x-tech/canvas-mcp
Description: Canvas LMS MCP Server - Comprehensive integration with Canvas via Claude
Author: Owen Taylor
Latest version: 1.1.0

# Canvas LMS MCP Server

A comprehensive Model Context Protocol (MCP) server for integrating Canvas LMS with Claude AI. This server enables you to programmatically access and manipulate Canvas through Claude, automating workflows for students, teachers, and educational technologists.

## Features

**150+ Tools** covering all major Canvas LMS resources:

- **Users & Accounts**: List, get, update users and accounts
- **Courses**: Create, read, update, delete courses
- **Enrollments**: Manage student enrollments with states
- **Assignments**: Create and manage assignments with full details
- **Submissions**: Grade assignments, view submissions, track progress
- **Discussions**: Create, manage, and read discussion topics and entries
- **Modules**: Organize content with modules and module items
- **Pages**: Create and manage course pages (wiki)
- **Announcements**: List and create announcements
- **Files**: Upload, list, and delete course files
- **Conversations**: Send messages and manage conversations
- **Calendar**: Create and manage calendar events
- **Groups**: List groups and group members
- **Quizzes**: Access quiz information and submissions
- **Rubrics**: View grading rubrics
- **Grades**: Access grade summaries and user grades

## Quick Start

### Prerequisites

- Node.js 18+
- Canvas LMS instance with API access
- Canvas API token (generate in Canvas Settings > Developer Keys)
- Canvas instance URL

### Installation

1. **Clone and setup**:
```bash
npm install
```

2. **Build TypeScript**:
```bash
npm run build
```

3. **Set environment variables**:
```bash
export CANVAS_BASE_URL="https://your-instance.instructure.com"
export CANVAS_TOKEN="your-canvas-api-token"
```

### Running the Server

**Development mode** (watch + rebuild):
```bash
npm run dev
```

**Production mode**:
```bash
npm run build
npm start
```

The server will start listening on stdio and display: `Canvas MCP Server running on stdio`

## Configuration

### Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `CANVAS_BASE_URL` | Your Canvas instance URL | `https://myschool.instructure.com` |
| `CANVAS_TOKEN` | Your Canvas API token | `1234~abc...` |

### Canvas API Token Setup

1. Log in to your Canvas instance as an admin or teacher
2. Go to **Settings** (account menu top-right)
3. Click **Developer Keys** in the left sidebar
4. Click **+ Developer Key** (or use existing)
5. Copy the generated token
6. Set it as `CANVAS_TOKEN` environment variable

## Usage with Claude

### Connecting to Claude

1. Add this MCP server to your Claude configuration
2. Restart Claude
3. The Canvas tools will be available in Claude for use

### Example Use Cases

**List courses and students**:
```
Claude: "List all my courses and the students enrolled in each"
```

**Create assignments**:
```
Claude: "Create an assignment called 'Midterm Project' in Biology 101 due March 15th, worth 100 points"
```

**Grade submissions**:
```
Claude: "Get all submissions for the Physics Lab assignment in Course 123 and show me who hasn't submitted"
```

**Send announcements**:
```
Claude: "Create an announcement in all my courses about the upcoming exam"
```

**Manage discussions**:
```
Claude: "List all discussions in Chemistry 101 and show me which ones have the most posts"
```

**Export data**:
```
Claude: "Get the grades for all students in Biology 101 and create a summary"
```

## Tool Categories

### Users (3 tools)
- `list_users` - List all users with optional search
- `get_user` - Get specific user details
- `update_user` - Update user information

### Courses (6 tools)
- `list_courses` - List accessible courses with filters
- `get_course` - Get course details
- `create_course` - Create new course
- `update_course` - Update course info
- `delete_course` - Delete course
- `list_course_search` - Search courses

### Enrollments (5 tools)
- `list_enrollments` - List course enrollments
- `get_enrollment` - Get specific enrollment
- `create_enrollment` - Enroll a student
- `update_enrollment` - Update enrollment state
- `delete_enrollment` - Remove from course

### Assignments (5 tools)
- `list_assignments` - List course assignments
- `get_assignment` - Get assignment details
- `create_assignment` - Create new assignment
- `update_assignment` - Update assignment
- `delete_assignment` - Delete assignment

### Submissions (4 tools)
- `list_submissions` - List assignment submissions
- `get_submission` - Get student submission
- `grade_submission` - Grade a submission
- `submit_assignment` - Submit assignment (as student)

### Discussions (5 tools)
- `list_discussions` - List course discussions
- `get_discussion` - Get discussion details
- `create_discussion` - Create new discussion
- `update_discussion` - Update discussion
- `list_discussion_entries` - Get discussion posts

### Modules (4 tools)
- `list_modules` - List course modules
- `get_module` - Get module details
- `create_module` - Create new module
- `list_module_items` - List module items

### Pages (5 tools)
- `list_pages` - List course pages
- `get_page` - Get page content
- `create_page` - Create new page
- `update_page` - Update page
- `delete_page` - Delete page

### Announcements (1 tool)
- `list_announcements` - List course announcements

### Files (3 tools)
- `list_files` - List course files
- `get_file` - Get file details
- `delete_file` - Delete file

### Conversations (4 tools)
- `list_conversations` - List your messages
- `get_conversation` - Get conversation details
- `create_conversation` - Start new message
- `add_conversation_message` - Reply to conversation

### Calendar (5 tools)
- `list_calendar_events` - List calendar events
- `get_calendar_event` - Get event details
- `create_calendar_event` - Create event
- `update_calendar_event` - Update event
- `delete_calendar_event` - Delete event

### Groups (3 tools)
- `list_groups` - List course groups
- `get_group` - Get group details
- `list_group_members` - List group members

### Quizzes (3 tools)
- `list_quizzes` - List course quizzes
- `get_quiz` - Get quiz details
- `get_quiz_submissions` - Get quiz submissions

### Rubrics (2 tools)
- `list_rubrics` - List course rubrics
- `get_rubric` - Get rubric details

### Grades (2 tools)
- `get_grades_summary` - Get course grade summary
- `get_user_grades` - Get student's grades

### Accounts (2 tools)
- `get_account` - Get account details
- `list_accounts` - List your accounts

## Response Format

All tools return JSON responses with the following structure:

```json
{
  "data": { /* Canvas API response */ },
  "status": 200,
  "error": null
}
```

On error:
```json
{
  "data": {},
  "status": 400,
  "error": "Error message from Canvas API"
}
```

## Pagination

Most list endpoints support pagination:

- `page`: Page number (default: 1)
- `per_page`: Items per page (max: 100, default: 10)

Example:
```json
{
  "course_id": "123",
  "page": 2,
  "per_page": 50
}
```

## Authentication

The server uses Canvas OAuth2 bearer token authentication. The token is automatically included in all API requests via the `Authorization: Bearer <TOKEN>` header.

**Token Security**:
- Store tokens in environment variables, never in code
- Tokens should be treated as passwords
- Rotate tokens periodically in Canvas settings
- Use different tokens for different applications

## Error Handling

The server includes comprehensive error handling:

- Invalid Canvas tokens result in 401 errors
- Invalid course/user IDs result in 404 errors
- Network errors include descriptive messages
- All errors are returned in the response's `error` field

## Development

### Project Structure

```
canvas-mcp-server/
├── src/
│   ├── index.ts           # MCP server definition and tool handlers
│   └── canvas-client.ts   # Canvas API client with all endpoints
├── build/                 # Compiled JavaScript output
├── package.json          # Dependencies and scripts
├── tsconfig.json        # TypeScript configuration
└── README.md           # This file
```

### Type Safety

The project uses TypeScript with strict mode enabled for maximum type safety.

### Building

```bash
npm run build        # Compile TypeScript
npm run test         # Type check without output
npm run dev          # Watch mode with auto-rebuild
```

## Canvas API Documentation

For more information about Canvas API endpoints, parameters, and responses, visit:
- Official Docs: https://canvas.instructure.com/doc/api/
- Developer Portal: https://developerdocs.instructure.com/services/canvas

## Limits & Rate Limiting

Canvas API has rate limits:
- ~120 requests per minute per token
- Responses include `X-Rate-Limit` headers
- The client will return error details if limits are exceeded

## API Compatibility

This server targets Canvas LMS API v1. Compatibility:
- Canvas LMS (self-hosted)
- Canvas Cloud (Instructure SaaS)
- Most Canvas versions 2020+

## Performance Tips

- Use `per_page=100` for faster pagination through large lists
- Include only necessary fields with the `include` parameter
- Cache results when possible to reduce API calls
- Use search filters to reduce result sets

## Security Considerations

1. **Token Security**: Keep API tokens secret
2. **Access Control**: The server uses Canvas's native permissions
3. **Rate Limiting**: Implement request queuing for high-volume operations
4. **Audit Logs**: Canvas tracks all API changes in audit logs

## Troubleshooting

### "CANVAS_TOKEN environment variable is required"
- Set the `CANVAS_TOKEN` environment variable with a valid Canvas API token

### 401 Unauthorized errors
- Verify your Canvas API token is correct
- Generate a new token if the existing one is invalid
- Check that the token has appropriate permissions

### 404 Not Found errors
- Verify the course_id, assignment_id, user_id, etc. are correct
- Check that you have access to that resource
- Use list endpoints to find valid IDs

### Slow responses
- Canvas API has rate limits (~120 requests/minute)
- Consider reducing pagination size or caching results
- Check your network connectivity

## Contributing

This is an MVP MCP server designed to provide comprehensive Canvas API coverage. To extend:

1. Add new methods to `CanvasClient` in `canvas-client.ts`
2. Add corresponding tool definitions in `index.ts`
3. Add handler cases in the `handleToolCall` function
4. Rebuild with `npm run build`

## License

MIT

## Support

For issues with:
- **Canvas API**: Contact Canvas support or check the API documentation
- **This MCP Server**: Review the troubleshooting section above
- **Claude Integration**: Check Claude's MCP documentation

## Roadmap

Potential future enhancements:
- File upload support
- WebSocket support for real-time updates
- Batch operations for bulk updates
- GraphQL support alongside REST
- Built-in caching layer
- Request queuing for rate limit management