canvas-student-mcp

API 토큰이 비활성화된 학교에서도 작동하는 Canvas LMS MCP 서버입니다.

Claude(또는 모든 MCP 클라이언트)에게 Canvas 계정에 대한 실시간 읽기 전용 액세스를 제공합니다: 강좌, 강의 계획서, 제출 상태가 포함된 과제, 성적, 공지사항, 모듈, 페이지, 파일, 토론, 퀴즈, 할 일, 캘린더. Notion 커넥터와 함께 사용하면 하나의 프롬프트로 전체 강좌를 보관할 수 있습니다.

또 다른 Canvas MCP인 이유는?

이미 몇 가지 훌륭한 Canvas MCP 서버가 존재합니다 — vishalsachdev/canvas-mcp, DMontgomery40/mcp-canvas-lms, mtgibbs/canvas-lms-mcp 등. 이 모든 서버는 개인 API 토큰이 필요합니다.

여기에 문제가 있습니다: 많은 대학에서 학생의 셀프 서비스 토큰 생성을 비활성화합니다. 계정 → 설정을 열어도 + 새 액세스 토큰 버튼이 전혀 없습니다. 그런 학교에서는 모든 토큰 기반 서버가 막다른 길입니다.

이 서버는 세션 쿠키 인증으로 이 문제를 해결합니다: 브라우저에서 Canvas에 로그인하고, 세션 쿠키를 한 번 복사하면 연결됩니다. Canvas 웹 UI는 동일한 /api/v1 REST API와 해당 쿠키로 통신하므로, Canvas 자체를 망가뜨리지 않고는 어떤 관리자 정책도 이를 차단할 수 없습니다.

내부적으로 필요한 것(토큰 기반 서버가 하지 않는 것):

• XSSI 가드 제거 — 쿠키로 인증된 Canvas 응답 앞에는 while(1);이 붙어 있어, 단순한 JSON 파싱을 깨뜨립니다.

• 로그인 리디렉션 감지 — 만료된 세션은 401을 반환하는 대신 로그인 페이지로 리디렉션합니다. 서버는 리디렉션과 JSON이 아닌 본문을 감지하고, 알 수 없는 오류를 발생시키는 대신 새로고침 방법을 정확히 알려줍니다.

• 자격 증명이 필요한 파일 다운로드 — 토큰 세션은 파일 URL을 자체 인증하도록 만드는 verifier= 매개변수를 얻습니다. 쿠키 세션은 그렇지 않으므로 다운로드 시 세션 쿠키를 전달해야 합니다(그렇지 않으면 Canvas가 500을 응답합니다). 리디렉션은 수동으로 처리되어 자격 증명이 CDN으로 전달되지 않습니다.

• 만료 인식 오류 — 모든 실패 모드는 오류 메시지 자체에 해결 방법을 설명합니다.

인증 외에도 차별화되는 설계 원칙:

• 설계상 읽기 전용. 모든 도구는 GET입니다. 서버는 물리적으로 과제를 제출하거나, 토론을 게시하거나, 어떤 것도 수정할 수 없습니다 — 자율 에이전트에 맡겨도 안전합니다.

• 컨텍스트 효율적인 응답. Canvas API 페이로드는 방대합니다. 모든 도구는 LLM이 실제로 필요로 하는 필드로만 자르고, HTML을 깨끗한 텍스트로 변환하며(링크 URL 보존), 명시적인 잘림 알림과 함께 페이지네이션을 제한합니다.

• 작고 감사 가능. 엄격한 TypeScript, 세 가지 런타임 종속성(MCP SDK, zod, PDF 텍스트용 unpdf). 학교 계정을 신뢰하기 전에 전체를 읽을 수 있습니다.

학교에서 허용하는 경우 토큰 인증도 여전히 지원됩니다 — 쿠키는 유일한 경로가 아니라 대체 수단입니다.

Related MCP server: canvas-parent-mcp

도구 (29개)

이 중 세 가지는 언급할 가치가 있습니다.

**canvas_read_file**은 강좌 자료를 읽을 수 있는 텍스트로 변환하여, "이번 주 슬라이드로 나를 시험해 봐" 또는 "지각 제출 정책이 뭐야"와 같은 요청이 실제로 작동하도록 만듭니다. PDF는 unpdf를 통해 처리됩니다. Office 형식은 저장소 내에서 처리됩니다 — .docx, .pptx, .xlsx는 XML의 ZIP 컨테이너이므로, Node 내장 zlib 위의 작은 ZIP 리더가 종속성 없이 세 가지를 모두 처리합니다. canvas_read_syllabus는 이를 기반으로 합니다: 강의 계획서가 파일 링크일 때 첨부 파일을 대신 읽는데, 이는 일반적인 경우입니다(테스트된 3개 강좌 중 2개). **canvas_grade_breakdown**은 Canvas의 두 가지 성적 모델(그룹별 가중치 및 총점)을 모두 구현하고, Canvas 자체가 보고하는 점수와 산술을 교차 검증하며, 드롭 규칙이나 게시되지 않은 과제 그룹이 예측을 신뢰할 수 없게 만드는 경우를 알려줍니다 — 조용히 잘못된 숫자를 반환하는 대신. **canvas_get_conversation**은 auto_mark_as_read=false를 전달하므로, 받은 편지함을 읽는 에이전트가 조용히 메시지를 읽음으로 표시하지 않습니다. 이 동작은 가정에 의존하지 않고 실제 읽지 않은 스레드에 대해 검증되었습니다.

다음 계획 및 쓰기가 의도적으로 범위에서 제외된 이유는 ROADMAP.md를 참조하세요.

빠른 시작

설치 불필요 — npx가 요청 시 가져옵니다:

npx canvas-student-mcp

또는 소스에서:

git clone https://github.com/xmike04/canvas-student-mcp.git
cd canvas-student-mcp
npm install && npm run build

자격 증명 얻기

옵션 A — API 토큰 (학교에서 허용하는 경우): Canvas → 계정 → 설정 → 승인된 통합 → + 새 액세스 토큰.

옵션 B — 세션 쿠키 (잠긴 학교용):

1. 브라우저에서 학교 Canvas에 로그인합니다.

2. DevTools (Cmd/Ctrl+Shift+I) → 네트워크 탭 → 새로고침

3. Canvas 도메인에 대한 아무 요청이나 클릭 → 요청 헤더 → 전체 cookie: 값을 복사합니다. (또는 canvas_session=... 쌍만 — 해당 쿠키 하나면 충분합니다)

두 자격 증명 모두 Canvas 계정에 대한 읽기 액세스 권한을 부여합니다. 비밀번호처럼 취급하세요.

자격 증명 저장 (macOS: 키체인 사용)

MCP 클라이언트 구성은 일반 텍스트 JSON입니다. macOS에서는 자격 증명을 완전히 밖에 보관할 수 있습니다:

security add-generic-password -s canvas-student-mcp -a cookie -w 'canvas_session=PASTE_VALUE_HERE' -U

API 토큰의 경우 -a cookie 대신 -a token을 사용하세요. 서버는 먼저 환경 변수를 확인한 다음 키체인을 확인하므로, 이는 옵트인이며 건너뛰어도 아무 문제가 없습니다. CANVAS_NO_KEYCHAIN=1은 조회를 비활성화합니다.

Claude에 등록

Claude Code — 키체인에 자격 증명이 있으면 구성에 비밀이 전혀 없습니다:

claude mcp add canvas --scope user \
  --env CANVAS_BASE_URL=https://yourschool.instructure.com \
  -- npx -y canvas-student-mcp

키체인 대신 자격 증명을 인라인으로 전달:

claude mcp add canvas --scope user \
  --env 'CANVAS_COOKIE=canvas_session=PASTE_VALUE_HERE' \
  --env CANVAS_BASE_URL=https://yourschool.instructure.com \
  -- npx -y canvas-student-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "canvas": {
      "command": "node",
      "args": ["/absolute/path/to/canvas-student-mcp/dist/index.js"],
      "env": {
        "CANVAS_COOKIE": "canvas_session=PASTE_VALUE_HERE",
        "CANVAS_BASE_URL": "https://yourschool.instructure.com"
      }
    }
  }
}

토큰 인증의 경우 CANVAS_COOKIE 대신 CANVAS_API_TOKEN을 사용하세요(둘 다 설정된 경우 토큰이 우선). 다음으로 확인: "내 Canvas 프로필을 확인해 줘."

쿠키가 만료되면(브라우저 세션이 종료되면), 모든 도구가 명확하게 알려줍니다 — 다시 복사하여 구성을 업데이트하세요. "로그인 유지"를 선택하면 세션은 일반적으로 몇 주 동안 지속됩니다.

에이전트 스킬

세 가지 패키징된 워크플로우가 skills/에 제공됩니다. 이 중 하나를 ~/.claude/skills/(또는 프로젝트의 .claude/skills/)에 복사하면, 요청이 적합할 때 Claude가 자동으로 사용합니다:

cp -R skills/canvas-morning-check ~/.claude/skills/

연결 후 물어볼 것들

• "앞으로 2주 동안 모든 수업에서 마감되는 것이 뭐야?"

• "각 강좌의 현재 성적은 어떻게 되고, 어떤 과제를 놓치고 있어?"

• "모든 강좌의 이번 주 공지사항을 요약해 줘."

• "내 BIOL 1710 강좌를 내보내서 Notion 학교 폴더에 보관해 줘." (Notion 커넥터 사용)

• "내 역사 강좌의 3주차 페이지를 읽고 나를 시험해 봐."

아키텍처 참고 사항

• stdio 전송, 상태 비저장 — 클라이언트 세션당 하나의 프로세스, 포트 없음, 원격 측정 없음, 저장소 없음. 데이터 흐름은 Canvas → 이 프로세스 → MCP 클라이언트, 그 외에는 없습니다.

• 자동 페이지네이션은 Canvas Link: rel="next" 헤더를 따르며, 명시적인 잘림 알림과 함께 최대 5페이지 × 100개 항목으로 제한되어 에이전트 컨텍스트가 제한된 상태를 유지합니다.

• 강의 계획서, 설명, 공지사항 및 페이지에 대한 HTML → 텍스트 변환 — 구조적 태그는 줄 바꿈/글머리 기호가 되고, 링크는 텍스트 (url)이 됩니다.

• 모든 도구에 Zod 입력 스키마; MCP 주석(readOnlyHint)이 전체에 선언됩니다.

개발

npm run build   # strict TypeScript compile
npm test        # smoke test: MCP handshake, all 30 tools register, error paths

스모크 테스트는 완전히 오프라인으로 실행됩니다. CI는 Canvas 계정이 필요하지 않으며, 실제 저장된 자격 증명이 테스트 실행에 유출되지 않도록 CANVAS_NO_KEYCHAIN=1을 설정합니다.

릴리스

퍼블리싱은 CI(.github/workflows/release.yml)에서 실행되므로 누구도 노트북에서 퍼블리싱하지 않습니다:

npm version minor && git push --follow-tags

태그를 푸시하면 빌드, 전체 테스트 스위트, 패키지 콘텐츠 검사, 태그가 package.json과 일치하는지 확인하는 가드가 트리거된 후 provenance와 함께 퍼블리싱됩니다. 이는 퍼블리시된 tarball을 이를 빌드한 커밋 및 워크플로우와 암호화 연결합니다. Actions 탭에서 워크플로우를 수동으로 실행하면 퍼블리싱 외에 모든 작업을 드라이 런으로 수행합니다.

보안 모델

• 읽기 전용: 모든 Canvas 호출은 GET이며, 어떤 도구도 Canvas에 쓸 수 없습니다. 받은 편지함을 읽어도 메시지는 읽지 않은 상태로 남습니다.

• 자격 증명은 MCP 클라이언트의 환경 설정 또는 macOS 키체인에만 저장되며, 이 리포지토리의 디스크에 저장되거나 학교의 Canvas 도메인 외부로 전송되지 않습니다. 파일 다운로드는 자격 증명이 CDN에 전달되지 않도록 수동으로 리디렉션을 따릅니다.

• 언제든지 교체 가능: Canvas에서 로그아웃(또는 토큰 해지)하면 모든 곳에서 자격 증명이 무효화됩니다.

• canvas_auth_status는 어떤 자격 증명이 사용 중인지, 어디에 저장되어 있는지, 여전히 작동하는지 알려줍니다.

라이선스

MIT