Canvas LMS MCP 서버

Model Context Protocol 서버로, MCP 클라이언트(Claude Desktop, Claude Code 또는 MCP를 지원하는 다른 도구)가 Canvas LMS 계정에 읽기 전용으로 접근할 수 있게 해줍니다.

두 가지 질문에 답합니다:

• "내가 듣는 과목과 성적은?" — 현재 성적이 포함된 진행 중인 과목.

• "아직 제출할 과제와 마감일은?" — 마감일이 있는 미제출 과제.

통신은 표준 stdio 전송 방식을 사용하므로, 클라이언트가 서버를 하위 프로세스로 실행합니다. MCP 트래픽 외에는 stdout에 아무것도 출력되지 않습니다.

요구 사항

• Node.js 18.17 이상(서버는 내장 fetch를 사용)

• Canvas 개인 액세스 토큰

Related MCP server: Canvas MCP Server

설치

cd canvas-mcp-server
npm install

구성

두 변수 모두 필수입니다. 둘 중 하나라도 누락되면 서버는 명확한 메시지를 출력하고 종료됩니다.

Canvas 액세스 토큰 발급받기

1. Canvas에 로그인합니다.

2. **계정 → 설정(Account → Settings)**으로 이동합니다.

3. 승인된 통합(Approved Integrations) 아래에서 **+ 새 액세스 토큰(New Access Token)**을 클릭합니다.

4. 용도를 입력하고 (선택 사항) 만료일을 설정한 다음 **토큰 생성(Generate Token)**을 클릭합니다.

5. 토큰을 즉시 복사하세요. Canvas는 토큰을 한 번만 표시합니다.

토큰은 Canvas 계정의 모든 권한을 갖습니다. 버전 관리 시스템에 토큰을 포함하지 말고, 유출된 경우 같은 설정 페이지에서 토큰을 폐기하세요.

클라이언트 연결

MCP 클라이언트 설정에 서버를 추가하고 src/index.js의 절대 경로를 지정하세요:

{
  "mcpServers": {
    "canvas": {
      "command": "node",
      "args": ["/absolute/path/to/canvas-mcp-server/src/index.js"],
      "env": {
        "CANVAS_API_URL": "https://asu.instructure.com",
        "CANVAS_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

• Claude Desktop — claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\).

• Claude Code — claude mcp add canvas --env CANVAS_API_URL=... --env CANVAS_ACCESS_TOKEN=... -- node /absolute/path/to/canvas-mcp-server/src/index.js

설정을 편집한 후 클라이언트를 다시 시작하세요.

도구

list_courses_and_grades

학생으로 현재 등록된 모든 과목과 현재 성적을 반환합니다.

기관에서 성적 평가 기간(grading period)을 사용하는 경우 Canvas는 성적을 두 번 보고합니다. 한 번은 진행 중인 평가 기간에 대한 것이고, 다른 한 번은 전체 과목에 대한 것입니다. grades.scope 필드가 어느 것을 가리키는지 나타냅니다:

• current_grading_period — 점수는 진행 중인 평가 기간을 기준으로 하며, course_total_score / course_total_grade는 전체 과목 성적을 나타냅니다.

• course_total — 기관에서 평가 기간을 사용하지 않으므로, 점수는 전체 과목 성적입니다.

• unavailable — Canvas가 성적 데이터가 포함된 등록 정보를 반환하지 않았습니다.

두 범위 모두에서 current_*는 아직 채점되지 않은 과제를 무시하고, final_*는 채점되지 않은 과제를 0점으로 계산합니다.

{
  "courses": [
    {
      "id": "101",
      "name": "Full Stack Web Development",
      "course_code": "GIT-411",
      "term": "Fall 2026",
      "term_start": "2026-08-20T00:00:00Z",
      "term_end": "2026-12-18T00:00:00Z",
      "enrollment_state": "active",
      "grades": {
        "current_score": 88.0,
        "current_grade": "B+",
        "final_score": 80.5,
        "final_grade": "B-",
        "scope": "current_grading_period",
        "grading_period_title": "Fall Term",
        "course_total_score": 91.4,
        "course_total_grade": "A-"
      },
      "html_url": "https://asu.instructure.com/courses/101"
    }
  ],
  "course_count": 1,
  "retrieved_at": "2026-09-01T12:00:00.000Z"
}

list_upcoming_assignments

진행 중인 과목 중 아직 제출하지 않은 과제를 마감일이 가까운 순서대로 정렬하여 반환합니다.

과제가 "미제출(outstanding)"로 간주되는 조건은 게시(published)되었고 채점 가능(gradable)하며 아직 제출·채점·면제되지 않은 경우입니다. 구체적으로 다음 항목은 제외됩니다:

• 제출 타임스탬프가 있는 항목

• submitted, pending_review 또는 graded 상태의 제출물

• 면제된 과제

• 이미 점수나 성적이 부여된 과제(수동 입력 또는 대면 제출)

• not_graded 과제(출석 체크 등)

• 게시되지 않은 과제

{
  "assignments": [
    {
      "id": "9004",
      "name": "Missed lab writeup",
      "course_id": "101",
      "course_name": "Full Stack Web Development",
      "due_at": "2026-08-28T06:59:00.000Z",
      "days_until_due": -4.2,
      "overdue": true,
      "points_possible": 25,
      "submission_types": ["online_upload"],
      "submission_state": "unsubmitted",
      "missing": true,
      "locked": false,
      "unlock_at": null,
      "lock_at": null,
      "html_url": "https://asu.instructure.com/courses/101/assignments/9004"
    }
  ],
  "assignment_count": 1,
  "courses_checked": 2,
  "window": {
    "from": "2026-09-01T12:00:00.000Z",
    "to": "2026-09-15T12:00:00.000Z",
    "include_overdue": true,
    "include_undated": false
  },
  "errors": [],
  "retrieved_at": "2026-09-01T12:00:00.000Z"
}

하나의 과목을 읽을 수 없는 경우(제한됨, 종료됨 또는 기타 오류) 해당 과목은 errors에 나열되고 나머지 과목은 계속 결과를 반환합니다.

동작 참고 사항

• 페이지네이션. Canvas는 모든 컬렉션을 Link 헤더로 페이지네이션합니다. 클라이언트는 페이지당 100개 레코드 기준으로 rel="next"를 따라가며, 엔드포인트당 최대 20페이지로 제한되어 잘못된 응답으로 인한 무한 루프를 방지합니다.

• 동시성. 과제는 한 번에 최대 5개 과목씩 가져와 Canvas 속도 제한을 피합니다.

• 현재 학기. 기본적으로 종료되지 않은 학기의 과목만 반환됩니다. Canvas의 기본 학기는 종료일이 없으므로 항상 포함됩니다.

• 오류. Canvas 오류는 MCP 도구 오류로 반환되며, 상태 코드와 Canvas의 원본 메시지, 그리고 일반적인 경우에 대한 힌트(401 → 토큰 오류, 404 → 잘못된 URL)가 포함됩니다.

• 읽기 전용. 두 도구 모두 readOnlyHint로 주석 처리되어 있습니다. 서버는 GET 요청만 보내며 Canvas 데이터를 절대 수정하지 않습니다.

개발

npm test    # 36 tests: API client, grade logic, filtering, and an end-to-end MCP round trip

테스트 스위트는 기록된 Canvas 페이로드와 함께 fetch 대체 구현을 사용하므로 네트워크나 실제 토큰이 필요하지 않습니다. 모든 픽스처 날짜는 테스트 실행 시점을 기준으로 상대적입니다.

src/
  index.js        MCP server: tool definitions, schemas, stdio wiring
  canvas.js       Canvas REST client: auth, pagination, error mapping
  courses.js      Active-course and grade normalization
  assignments.js  Outstanding-assignment filtering and due-date windows

라이선스

MIT