Skip to content

common_issues.md

Latest commit

 

History

History
315 lines (229 loc) · 7.53 KB

common_issues.md

File metadata and controls

315 lines (229 loc) · 7.53 KB

Common Issues and Solutions

Quick fixes for the most common problems with Canvas MCP.

Installation Issues

"canvas-mcp-server: command not found"

Problem: The CLI command isn't available after installation.

Solution:

# Make sure you installed with the editable flag
uv pip install -e .

# Or reinstall
pip uninstall canvas-mcp
uv pip install -e .

# Verify it worked
canvas-mcp-server --help

"No module named 'canvas_mcp'"

Problem: Package not installed correctly.

Solution:

# Navigate to the canvas-mcp directory
cd /path/to/canvas-mcp

# Install in editable mode
uv pip install -e .

Configuration Issues

"Authentication failed"

Problem: Canvas API token is invalid or expired.

Solution:

  1. Go to Canvas → Account → Settings
  2. Scroll to "Approved Integrations"
  3. Delete the old token if present
  4. Create a new access token
  5. Update your .env file with the new token
  6. Restart your MCP client

"Canvas API URL is invalid"

Problem: Wrong URL format in .env.

Solution: Your Canvas API URL should look like:

CANVAS_API_URL=https://your-institution.instructure.com/api/v1

NOT:

  • ❌ https://your-institution.instructure.com/ (missing /api/v1)
  • ❌ your-institution.instructure.com/api/v1 (must include https://)
  • ❌ https://your-institution.instructure.com/api/v1/ (no trailing slash)

Test with:

canvas-mcp-server --test

"Cannot create access token" (Students)

Problem: Your institution restricts student API access.

Solution: Contact your Canvas administrator or IT help desk:

Hi, I'm trying to use the Canvas API to track my assignments
and grades. Could you help me create an API access token or
enable API access for my account?

Most institutions will enable this for legitimate educational purposes.

Runtime Issues

"Rate limit exceeded (429 errors)"

Problem: Making too many API requests too quickly.

Good news: Canvas MCP now automatically handles rate limiting!

What happens:

  • Canvas MCP detects rate limit errors
  • Automatically waits and retries (up to 3 times)
  • Shows progress: "⏳ Rate limited (429). Retrying in 4s..."

If it still fails:

  • Wait a few minutes before trying again
  • For bulk operations, the code execution API is more efficient

"Tool not showing up in Claude Desktop"

Problem: Canvas MCP tools aren't available in Claude.

Solution:

  1. Check your MCP client's configuration file:

    Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json Cursor (macOS/Linux): ~/.cursor/mcp_config.json Windsurf (macOS): ~/Library/Application Support/Windsurf/mcp_config.json Zed: Settings → Open Settings (settings.json)

    Ensure it contains:

    {
  "mcpServers": {
    "canvas-api": {
      "command": "canvas-mcp-server"
    }
  }
}

    Or for Zed:

    {
  "context_servers": {
    "canvas-api": {
      "command": {
        "path": "/absolute/path/to/canvas-mcp-server",
        "args": []
      }
    }
  }
}

  2. Restart your MCP client completely:

    • Quit the application (not just close the window)
    • Reopen it

  3. Check for errors:

    • For Claude Desktop: Look in the developer console
    • For other clients: Check client logs or developer console
    • Or run manually: canvas-mcp-server and check for errors

"Data seems outdated"

Problem: Seeing old information.

Solution: Canvas MCP caches some data for performance. The cache TTL is set in your .env:

CACHE_TTL=300  # 5 minutes (default)

To see fresh data immediately:

  • Restart the MCP server (restart your MCP client)
  • Or wait for cache to expire (default: 5 minutes)

Data Issues

"Student names showing as Student_xxxxxxxx"

This is working correctly! If you have anonymization enabled:

ENABLE_DATA_ANONYMIZATION=true

This is for FERPA compliance. Student data is anonymized before reaching Claude.

To disable (only if you don't need FERPA compliance):

ENABLE_DATA_ANONYMIZATION=false

Then restart your MCP client.

"Missing some courses or assignments"

Problem: Not all data is showing up.

Possible causes:

  1. Canvas permissions: Your API token might not have access to all courses

    • Solution: Check your Canvas role and permissions

  2. Archived courses: Old courses might be archived

    • Solution: Unarchive in Canvas if needed

  3. Pagination issue: Very large datasets might not load completely

    • Solution: Be more specific (e.g., "Show assignments in CS 101" instead of "Show all assignments")

Performance Issues

"Bulk operations are very slow"

Problem: Grading or analyzing large datasets takes too long.

Solution: Use the code execution API for bulk operations:

Instead of:

Show me all 90 student submissions and grade them

Use:

Use the bulk grading code API to grade all submissions for Assignment 5

This is 99.7% more efficient for large datasets!

"AI assistant seems to get confused with lots of data"

Problem: Too much data in context.

Solution:

  • Be specific about what you want
  • Use filters (course names, assignment IDs, date ranges)
  • For large operations, use code execution to keep data out of your AI assistant's context

Example:

Show me students who haven't submitted Assignment 3 in CS 101

Instead of:

Show me all students and all their submissions

Integration Issues

"Works in terminal but not in MCP client"

Problem: canvas-mcp-server works manually but not through your MCP client.

Solution:

  1. Check the command path:

    which canvas-mcp-server

  2. Use full path in config if needed:

    For Claude Desktop, Cursor, Windsurf, Continue:

    {
  "mcpServers": {
    "canvas-api": {
      "command": "/full/path/to/canvas-mcp-server"
    }
  }
}

    For Zed:

    {
  "context_servers": {
    "canvas-api": {
      "command": {
        "path": "/full/path/to/canvas-mcp-server",
        "args": []
      }
    }
  }
}

  3. Check environment variables: Your MCP client might not have access to your .env

    • Make sure .env is in the canvas-mcp directory
    • Or set CANVAS_API_TOKEN and CANVAS_API_URL as system environment variables

Getting More Help

  1. Enable debug mode in your .env:

    DEBUG=true
LOG_API_REQUESTS=true

  2. Test the connection:

    canvas-mcp-server --test

  3. Check the logs: Run the server manually to see error messages

  4. Still stuck?

    • Open an issue
    • Include:
      • Error messages (redact your API token!)
      • Your Canvas instance URL (e.g., "your-institution.instructure.com")
      • What you were trying to do
      • Output from canvas-mcp-server --test

Quick Diagnostic Checklist

Run through this list:

  • .env file exists and has CANVAS_API_TOKEN and CANVAS_API_URL
  • Canvas API token is valid (test in Canvas web UI)
  • canvas-mcp-server --test succeeds
  • Claude Desktop config includes canvas-mcp
  • Restarted Claude Desktop after config changes
  • Canvas API URL doesn't have trailing slash or /api/v1

If all these pass and it still doesn't work, open an issue!