# Canvas MCP

Read-only FastMCP server for Canvas LMS study data.

This project is configured for CIAM Canvas by default:

```text
https://ciam.instructure.com
```

## Configuration

Set these environment variables before starting the server:

```bash
export CANVAS_BASE_URL="https://ciam.instructure.com"
export CANVAS_API_TOKEN="your-canvas-token"
```

Do not commit real Canvas tokens.

## Install

```bash
cd /Users/zihanwang/Documents/Codex/canvas-mcp
uv sync --extra dev
```

## Run

```bash
cd /Users/zihanwang/Documents/Codex/canvas-mcp
uv run canvas-mcp
```

The server speaks MCP over stdio.

## MCP Client Config

Use this shape in an MCP client config. Replace `your-canvas-token` with your token in your local config only.

```json
{
  "mcpServers": {
    "canvas": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/zihanwang/Documents/Codex/canvas-mcp",
        "run",
        "canvas-mcp"
      ],
      "env": {
        "CANVAS_BASE_URL": "https://ciam.instructure.com",
        "CANVAS_API_TOKEN": "your-canvas-token"
      }
    }
  }
}
```

## Tools

- `canvas_self`: current Canvas user.
- `canvas_courses`: visible courses, defaulting to active enrollments.
- `canvas_course_assignments`: assignments for a course.
- `canvas_upcoming_events`: upcoming calendar events.
- `canvas_todo`: todo items for the current user.
- `canvas_course_modules`: modules and module items for a course.
- `canvas_course_pages`: wiki pages for a course, with optional search.
- `canvas_course_files`: files for a course, with optional folder filtering.
- `canvas_submissions`: assignment submissions or visible course submissions.
- `canvas_raw_get`: read-only escape hatch for `/api/v1/...` Canvas paths.

## Local Verification

```bash
cd /Users/zihanwang/Documents/Codex/canvas-mcp
uv run pytest -v
uv run python -c "from canvas_mcp.server import mcp; print(mcp.name)"
```

Expected output from the smoke test:

```text
Canvas LMS
```

## Live API Smoke Test

After setting `CANVAS_API_TOKEN`, this should return your Canvas user profile:

```bash
cd /Users/zihanwang/Documents/Codex/canvas-mcp
uv run python - <<'PY'
from canvas_mcp.client import CanvasClient, CanvasConfig

client = CanvasClient(CanvasConfig.from_env())
try:
    print(client.get("users/self", paginate=False))
finally:
    client.close()
PY
```