Common Issues and Solutions

August 24, 2026 · View on GitHub

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:

Go to Canvas → Account → Settings
Scroll to "Approved Integrations"
Delete the old token if present
Create a new access token (see below if your institution gates this)
Update your .env file with the new token
Restart your MCP client

Note that many institutions now issue short-lived tokens — Instructure pushed a 30-day default in 2026 — so "it worked last month" does not mean the token is still valid.

"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

Problem: Your institution restricts self-service API token creation. The "New Access Token" button is missing or errors out. At some schools this applies to students only; at others it applies to everyone, instructors included.

Solution: First check whether your institution has a token request form — search its IT knowledge base for "Canvas API token". If it does, that form is the only path; the Canvas UI will keep refusing.

University of Illinois Urbana-Champaign: use the Canvas API Token Request form. After approval, activate the token under Account → Settings → Approved Integrations, then retrieve its value from the U of I Box link Technology Services sends you. Illinois tokens expire after 30 days as of August 2026 (KB 150325).

Otherwise, 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:

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": []
      }
    }
  }
}
```
Restart your MCP client completely:
- Quit the application (not just close the window)
- Reopen it
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 supports FERPA-conscious workflows by reducing identity data before tool output reaches the AI client. It does not by itself establish compliance.

To disable (only after reviewing your institution's privacy requirements):

ENABLE_DATA_ANONYMIZATION=false

Then restart your MCP client.

"Missing some courses or assignments"

Problem: Not all data is showing up.

Possible causes:

Canvas permissions: Your API token might not have access to all courses
- Solution: Check your Canvas role and permissions
Archived courses: Old courses might be archived
- Solution: Unarchive in Canvas if needed
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 keeps per-item processing out of the model's context; actual token use depends on the workload and selected output.

"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:

Check the command path:
```
which canvas-mcp-server
```

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": []
      }
    }
  }
}

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

Enable debug mode in your .env:
```
DEBUG=true
LOG_API_REQUESTS=true
```
Test the connection:
```
canvas-mcp-server --test
```
Check the logs: Run the server manually to see error messages
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!