riverpease15/canvas-mcp-server

Canvas LMS MCP Server

A local Model Context Protocol (MCP) server that enables Claude Desktop to interact with Canvas LMS. Get real-time access to your courses, assignments, grades, and announcements directly through Claude.

🚀 Quick Start

1. Clone and Install

# Clone the repository (update URL with your actual GitHub repository)
git clone https://github.com/yourusername/canvas-mcp-server-modern.git
cd canvas-mcp-server-modern

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

2. Get Your Canvas API Token

1. Log into your Canvas instance
2. Navigate to Account Settings:
   • Click on your profile picture/avatar in the top-right corner
   • Select "Account" from the dropdown
   • Click "Settings" in the left sidebar
3. Generate Access Token:
   • Scroll down to "Approved Integrations"
   • Click "+ New Access Token"
   • Give it a name like "Claude MCP Server"
   • Copy the token immediately (you won't be able to see it again!)

3. Configure Environment

You have two options for setting your Canvas credentials:

Option A: Environment File (Recommended for development)

# Copy the example environment file
cp env.example .env

# Edit the .env file with your Canvas details
nano .env  # or use your preferred text editor

Add your Canvas details to .env:

# Your Canvas instance URL (without trailing slash)
CANVAS_BASE_URL=https://your-school.instructure.com

# Your Canvas API access token
CANVAS_ACCESS_TOKEN=your_access_token_here

# Optional: Request timeout in seconds (default: 30)
CANVAS_TIMEOUT=30

Option B: Claude Desktop Config Only

If you prefer to set credentials only in Claude Desktop config, you can skip the .env file. The credentials will be set directly in the Claude Desktop configuration in the next step.

🔧 Environment Configuration Approaches

Approach 1: Using .env File

How it works: Environment variables are loaded from a .env file in the project directory.

Pros:

• ✅ Easy local testing - Run python server.py directly for development
• ✅ Version control friendly - .env.example can be committed, actual .env is gitignored
• ✅ Multiple environments - Easy to switch between different Canvas instances
• ✅ Development convenience - Quick credential changes without editing Claude config
• ✅ IDE integration - Most IDEs automatically load .env files

Cons:

• ❌ Extra file to manage - Need to create and maintain .env file
• ❌ Security consideration - Risk of accidentally committing .env file
• ❌ Path dependency - Must run from project directory

Best for: Developers, people who test locally, users with multiple Canvas instances

Approach 2: Claude Desktop Config Only

How it works: Environment variables are set directly in the Claude Desktop configuration file.

Pros:

• ✅ Simpler setup - No extra files to create or manage
• ✅ Centralized configuration - All MCP settings in one place
• ✅ Cleaner project - No credential files in project directory
• ✅ Less error-prone - No risk of accidentally committing credentials
• ✅ Portable - Works regardless of project directory location

Cons:

• ❌ Harder local testing - Need to set environment variables manually for python server.py
• ❌ Config file editing - Must edit Claude Desktop config for credential changes
• ❌ Less flexible - Harder to switch between different Canvas instances quickly

Best for: End users, production deployments, people who only use Claude Desktop

Recommendation

• For development/testing: Use the .env file approach
• For production/end-user: Use Claude Desktop config only
• For flexibility: Keep both options available (as documented in this README)

4. Test the Connection

If using .env file:

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Test the server locally
python server.py

If using Claude Desktop config only (no .env file):

# Set environment variables manually for testing
export CANVAS_BASE_URL="https://your-school.instructure.com"
export CANVAS_ACCESS_TOKEN="your_access_token_here"

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Test the server locally
python server.py

You should see output indicating successful connection to Canvas.

5. Configure for Claude Desktop

The Canvas MCP server integrates with Claude Desktop through configuration rather than a separate installation step. See the Claude Desktop Integration section below for detailed setup instructions.

🔧 Claude Desktop Integration

Configure Claude Desktop

1. Open Claude Desktop settings:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the Canvas MCP server to your config:

{
  "mcpServers": {
    "canvas": {
      "command": "/absolute/path/to/canvas-mcp-server-modern/.venv/bin/python",
      "args": ["/absolute/path/to/canvas-mcp-server-modern/server.py"],
      "env": {
        "CANVAS_BASE_URL": "https://your-school.instructure.com",
        "CANVAS_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

Note: If you're using a .env file for configuration, you can omit the env section from the Claude Desktop config since the environment variables will be loaded automatically from the file.

3. Restart Claude Desktop

Verify Integration

Once configured, you can ask Claude things like:

• "What are my assignments due this week?"
• "Show me my current grades"
• "What announcements were posted recently?"
• "List all my active courses"
• "Are there any overdue assignments I need to complete?"
• "What are my to-dos for my Machine Learning class?"

📚 Available Tools

Course Management

• list_courses - List all active courses with enrollment information
• check_grades_status - Get current grades and scores for all active courses

Assignment Management

• get_upcoming_assignments - Get all upcoming assignments across courses
• get_todo_items - Get Canvas native to-do items

Announcements

• get_recent_announcements - Get recent announcements from all active courses

Resources

• canvas://connection-status - Check Canvas connection status
• canvas://available-tools - List all available tools

🛠️ Development

Local Development

# Activate virtual environment
source .venv/bin/activate

# Run in development mode with hot reload
mcp dev server.py

Note: If you're using Claude Desktop config only (no .env file), you'll need to set environment variables manually for development:

# Set environment variables for development
export CANVAS_BASE_URL="https://your-school.instructure.com"
export CANVAS_ACCESS_TOKEN="your_access_token_here"

# Then run development mode
mcp dev server.py

Testing Individual Functions

# Test the server directly
python server.py

# Test specific functionality
python -c "
import asyncio
from server import list_courses
result = asyncio.run(list_courses())
print(result)
"

🔍 Troubleshooting

Common Issues

1. "Invalid Canvas access token"

• Solution: Generate a new access token from Canvas Account Settings
• Check: Ensure the token hasn't expired and has proper permissions

2. "Network error connecting to Canvas"

• Solution: Verify your CANVAS_BASE_URL is correct (no trailing slash)
• Check: Ensure your school's Canvas instance is accessible

3. "Insufficient permissions for Canvas API"

• Solution: Your Canvas account may have restricted API access
• Contact: Your school's IT administrator if you need API permissions

4. Claude Desktop not recognizing the server

• Solution:
  1. Verify the absolute path in your config file
  2. Ensure the virtual environment is activated when running Claude Desktop
  3. Check that all dependencies are installed

5. Environment variables not loading

• If using .env file:
  1. Ensure .env file is in the same directory as server.py
  2. Check that environment variables are properly formatted (no spaces around =)
  3. Restart Claude Desktop after making changes
• If using Claude Desktop config only:
  1. Verify the env section in your Claude Desktop config has the correct values
  2. Ensure no .env file exists that might override the config values
  3. Restart Claude Desktop after making changes

Debug Mode

Enable debug logging by setting the log level:

export MCP_LOG_LEVEL=DEBUG
python server.py

Testing Canvas API Access

Test your Canvas credentials directly:

python -c "
import asyncio
import os
from dotenv import load_dotenv
from server import get_canvas_client

load_dotenv()

async def test():
    try:
        client = await get_canvas_client()
        result = await client.test_connection()
        print('Connection test:', result)
        await client.close()
    except Exception as e:
        print('Error:', e)

asyncio.run(test())
"

📋 Requirements

• Python 3.10+
• Canvas LMS account with API access
• Claude Desktop application

🔒 Security Notes

• Never commit your .env file - it contains sensitive credentials
• Keep your Canvas access token secure - treat it like a password
• Regenerate tokens periodically for better security
• Use environment variables in production deployments

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test them
4. Commit your changes: git commit -am 'Add some feature'
5. Push to the branch: git push origin feature-name
6. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

If you encounter issues:

1. Check the troubleshooting section above
2. Search existing issues on GitHub
3. Create a new issue with:
   • Your Canvas instance URL (without credentials)
   • Python version
   • Operating system
   • Error messages (without sensitive data)