Canvas MCP Server V2.0

Instructions

Implementation Reference

• src/index.ts:284-294 (schema)

  Tool schema definition including name, description, and input schema for 'canvas_list_files'.

    name: "canvas_list_files",
    description: "List files in a course or folder",
    inputSchema: {
      type: "object",
      properties: {
        course_id: { type: "number", description: "ID of the course" },
        folder_id: { type: "number", description: "ID of the folder (optional)" }
      },
      required: ["course_id"]
    }
  },

• src/index.ts:1239-1247 (handler)

  Tool handler that extracts parameters, validates course_id, calls CanvasClient.listFiles, and returns JSON-formatted file list.

  case "canvas_list_files": {
    const { course_id, folder_id } = args as { course_id: number; folder_id?: number };
    if (!course_id) throw new Error("Missing required field: course_id");
    
    const files = await this.client.listFiles(course_id, folder_id);
    return {
      content: [{ type: "text", text: JSON.stringify(files, null, 2) }]
    };
  }

• src/client.ts:386-393 (helper)

  CanvasClient helper method implementing the core logic to fetch files from Canvas API endpoint based on course or folder ID.

  async listFiles(courseId: number, folderId?: number): Promise<CanvasFile[]> {
    const endpoint = folderId 
      ? `/folders/${folderId}/files`
      : `/courses/${courseId}/files`;
    
    const response = await this.client.get(endpoint);
    return response.data;
  }

• src/index.ts:1071-1073 (registration)

  Registration of tool list handler that exposes the TOOLS array including canvas_list_files to MCP clients.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: TOOLS
  }));

• src/index.ts:1076-1464 (registration)

  Registration of the main tool call handler that dispatches to specific tool implementations via switch on tool name.

  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    try {
      const args = request.params.arguments || {};
      const toolName = request.params.name;
      
      console.error(`[Canvas MCP] Executing tool: ${toolName}`);
      
      switch (toolName) {
        // Health check
        case "canvas_health_check": {
          const health = await this.client.healthCheck();
          return {
            content: [{ type: "text", text: JSON.stringify(health, null, 2) }]
          };
        }
  
        // Course management
        case "canvas_list_courses": {
          const { include_ended = false } = args as { include_ended?: boolean };
          const courses = await this.client.listCourses(include_ended);
          return {
            content: [{ type: "text", text: JSON.stringify(courses, null, 2) }]
          };
        }
  
        case "canvas_get_course": {
          const { course_id } = args as { course_id: number };
          if (!course_id) throw new Error("Missing required field: course_id");
          
          const course = await this.client.getCourse(course_id);
          return {
            content: [{ type: "text", text: JSON.stringify(course, null, 2) }]
          };
        }
        
        case "canvas_create_course": {
          const courseArgs = args as unknown as CreateCourseArgs;
          if (!courseArgs.account_id || !courseArgs.name) {
            throw new Error("Missing required fields: account_id and name");
          }
          const course = await this.client.createCourse(courseArgs);
          return {
            content: [{ type: "text", text: JSON.stringify(course, null, 2) }]
          };
        }
        
        case "canvas_update_course": {
          const updateArgs = args as unknown as UpdateCourseArgs;
          if (!updateArgs.course_id) {
            throw new Error("Missing required field: course_id");
          }
          const updatedCourse = await this.client.updateCourse(updateArgs);
          return {
            content: [{ type: "text", text: JSON.stringify(updatedCourse, null, 2) }]
          };
        }
  
        // Assignment management
        case "canvas_list_assignments": {
          const { course_id, include_submissions = false } = args as { 
            course_id: number; 
            include_submissions?: boolean 
          };
          if (!course_id) throw new Error("Missing required field: course_id");
          
          const assignments = await this.client.listAssignments(course_id, include_submissions);
          return {
            content: [{ type: "text", text: JSON.stringify(assignments, null, 2) }]
          };
        }
  
        case "canvas_get_assignment": {
          const { course_id, assignment_id, include_submission = false } = args as { 
            course_id: number; 
            assignment_id: number;
            include_submission?: boolean;
          };
          if (!course_id || !assignment_id) {
            throw new Error("Missing required fields: course_id and assignment_id");
          }
          
          const assignment = await this.client.getAssignment(course_id, assignment_id, include_submission);
          return {
            content: [{ type: "text", text: JSON.stringify(assignment, null, 2) }]
          };
        }
        
        case "canvas_create_assignment": {
          const assignmentArgs = args as unknown as CreateAssignmentArgs;
          if (!assignmentArgs.course_id || !assignmentArgs.name) {
            throw new Error("Missing required fields: course_id and name");
          }
          const assignment = await this.client.createAssignment(assignmentArgs);
          return {
            content: [{ type: "text", text: JSON.stringify(assignment, null, 2) }]
          };
        }
        
        case "canvas_update_assignment": {
          const updateAssignmentArgs = args as unknown as UpdateAssignmentArgs;
          if (!updateAssignmentArgs.course_id || !updateAssignmentArgs.assignment_id) {
            throw new Error("Missing required fields: course_id and assignment_id");
          }
          const updatedAssignment = await this.client.updateAssignment(updateAssignmentArgs);
          return {
            content: [{ type: "text", text: JSON.stringify(updatedAssignment, null, 2) }]
          };
        }
  
        case "canvas_list_assignment_groups": {
          const { course_id } = args as { course_id: number };
          if (!course_id) throw new Error("Missing required field: course_id");
          
          const groups = await this.client.listAssignmentGroups(course_id);
          return {
            content: [{ type: "text", text: JSON.stringify(groups, null, 2) }]
          };
        }
  
        // Submissions
        case "canvas_get_submission": {
          const { course_id, assignment_id, user_id } = args as { 
            course_id: number; 
            assignment_id: number;
            user_id?: number;
          };
          if (!course_id || !assignment_id) {
            throw new Error("Missing required fields: course_id and assignment_id");
          }
          
          const submission = await this.client.getSubmission(course_id, assignment_id, user_id || 'self');
          return {
            content: [{ type: "text", text: JSON.stringify(submission, null, 2) }]
          };
        }
  
        case "canvas_submit_assignment": {
          const submitArgs = args as unknown as SubmitAssignmentArgs;
          const { course_id, assignment_id, submission_type } = submitArgs;
  
          if (!course_id || !assignment_id || !submission_type) {
            throw new Error("Missing required fields: course_id, assignment_id, and submission_type");
          }
  
          const submission = await this.client.submitAssignment(submitArgs);
          return {
            content: [{ type: "text", text: JSON.stringify(submission, null, 2) }]
          };
        }
        
        case "canvas_submit_grade": {
          const gradeArgs = args as unknown as SubmitGradeArgs;
          if (!gradeArgs.course_id || !gradeArgs.assignment_id || 
              !gradeArgs.user_id || gradeArgs.grade === undefined) {
            throw new Error("Missing required fields for grade submission");
          }
          const submission = await this.client.submitGrade(gradeArgs);
          return {
            content: [{ type: "text", text: JSON.stringify(submission, null, 2) }]
          };
        }
  
        // Files
        case "canvas_list_files": {
          const { course_id, folder_id } = args as { course_id: number; folder_id?: number };
          if (!course_id) throw new Error("Missing required field: course_id");
          
          const files = await this.client.listFiles(course_id, folder_id);
          return {
            content: [{ type: "text", text: JSON.stringify(files, null, 2) }]
          };
        }
  
        case "canvas_get_file": {
          const { file_id } = args as { file_id: number };
          if (!file_id) throw new Error("Missing required field: file_id");
          
          const file = await this.client.getFile(file_id);
          return {
            content: [{ type: "text", text: JSON.stringify(file, null, 2) }]
          };
        }
  
        case "canvas_list_folders": {
          const { course_id } = args as { course_id: number };
          if (!course_id) throw new Error("Missing required field: course_id");
          
          const folders = await this.client.listFolders(course_id);
          return {
            content: [{ type: "text", text: JSON.stringify(folders, null, 2) }]
          };
        }
  
        // Pages
        case "canvas_list_pages": {
          const { course_id } = args as { course_id: number };
          if (!course_id) throw new Error("Missing required field: course_id");
          
          const pages = await this.client.listPages(course_id);
          return {
            content: [{ type: "text", text: JSON.stringify(pages, null, 2) }]
          };
        }
  
        case "canvas_get_page": {
          const { course_id, page_url } = args as { course_id: number; page_url: string };
          if (!course_id || !page_url) {
            throw new Error("Missing required fields: course_id and page_url");
          }
          
          const page = await this.client.getPage(course_id, page_url);
          return {
            content: [{ type: "text", text: JSON.stringify(page, null, 2) }]
          };
        }
  
        // Calendar
        case "canvas_list_calendar_events": {
          const { start_date, end_date } = args as { start_date?: string; end_date?: string };
          const events = await this.client.listCalendarEvents(start_date, end_date);
          return {
            content: [{ type: "text", text: JSON.stringify(events, null, 2) }]
          };
        }
  
        case "canvas_get_upcoming_assignments": {
          const { limit = 10 } = args as { limit?: number };
          const assignments = await this.client.getUpcomingAssignments(limit);
          return {
            content: [{ type: "text", text: JSON.stringify(assignments, null, 2) }]
          };
        }
  
        // Dashboard
        case "canvas_get_dashboard": {
          const dashboard = await this.client.getDashboard();
          return {
            content: [{ type: "text", text: JSON.stringify(dashboard, null, 2) }]
          };
        }
  
        case "canvas_get_dashboard_cards": {
          const cards = await this.client.getDashboardCards();
          return {
            content: [{ type: "text", text: JSON.stringify(cards, null, 2) }]
          };
        }
  
        // User management
        case "canvas_get_user_profile": {
          const profile = await this.client.getUserProfile();
          return {
            content: [{ type: "text", text: JSON.stringify(profile, null, 2) }]
          };
        }
  
        case "canvas_update_user_profile": {
          const profileData = args as Partial<{ name: string; short_name: string; bio: string; title: string; time_zone: string }>;
          const updatedProfile = await this.client.updateUserProfile(profileData);
          return {
            content: [{ type: "text", text: JSON.stringify(updatedProfile, null, 2) }]
          };
        }
  
        case "canvas_enroll_user": {
          const enrollArgs = args as unknown as EnrollUserArgs;
          if (!enrollArgs.course_id || !enrollArgs.user_id) {
            throw new Error("Missing required fields: course_id and user_id");
          }
          const enrollment = await this.client.enrollUser(enrollArgs);
          return {
            content: [{ type: "text", text: JSON.stringify(enrollment, null, 2) }]
          };
        }
  
        // Grades
        case "canvas_get_course_grades": {
          const { course_id } = args as { course_id: number };
          if (!course_id) throw new Error("Missing required field: course_id");
          
          const grades = await this.client.getCourseGrades(course_id);
          return {
            content: [{ type: "text", text: JSON.stringify(grades, null, 2) }]
          };
        }
  
        case "canvas_get_user_grades": {
          const grades = await this.client.getUserGrades();
          return {
            content: [{ type: "text", text: JSON.stringify(grades, null, 2) }]
          };
        }
  
        // Continue with all other tools...
        // [I'll include the rest in the same pattern]
        
        // Account Management
        case "canvas_get_account": {
          const { account_id } = args as { account_id: number };
          if (!account_id) throw new Error("Missing required field: account_id");
          
          const account = await this.client.getAccount(account_id);
          return {
            content: [{ type: "text", text: JSON.stringify(account, null, 2) }]
          };
        }
  
        case "canvas_list_account_courses": {
          const accountCoursesArgs = args as unknown as ListAccountCoursesArgs;
          if (!accountCoursesArgs.account_id) {
            throw new Error("Missing required field: account_id");
          }
          
          const courses = await this.client.listAccountCourses(accountCoursesArgs);
          return {
            content: [{ type: "text", text: JSON.stringify(courses, null, 2) }]
          };
        }
  
        case "canvas_list_account_users": {
          const accountUsersArgs = args as unknown as ListAccountUsersArgs;
          if (!accountUsersArgs.account_id) {
            throw new Error("Missing required field: account_id");
          }
          
          const users = await this.client.listAccountUsers(accountUsersArgs);
          return {
            content: [{ type: "text", text: JSON.stringify(users, null, 2) }]
          };
        }
  
        case "canvas_create_user": {
          const createUserArgs = args as unknown as CreateUserArgs;
          if (!createUserArgs.account_id || !createUserArgs.user || !createUserArgs.pseudonym) {
            throw new Error("Missing required fields: account_id, user, and pseudonym");
          }
          
          const user = await this.client.createUser(createUserArgs);
          return {
            content: [{ type: "text", text: JSON.stringify(user, null, 2) }]
          };
        }
  
        case "canvas_list_sub_accounts": {
          const { account_id } = args as { account_id: number };
          if (!account_id) throw new Error("Missing required field: account_id");
          
          const subAccounts = await this.client.listSubAccounts(account_id);
          return {
            content: [{ type: "text", text: JSON.stringify(subAccounts, null, 2) }]
          };
        }
  
        case "canvas_get_account_reports": {
          const { account_id } = args as { account_id: number };
          if (!account_id) throw new Error("Missing required field: account_id");
          
          const reports = await this.client.getAccountReports(account_id);
          return {
            content: [{ type: "text", text: JSON.stringify(reports, null, 2) }]
          };
        }
  
        case "canvas_create_account_report": {
          const createReportArgs = args as unknown as CreateReportArgs;
          if (!createReportArgs.account_id || !createReportArgs.report) {
            throw new Error("Missing required fields: account_id and report");
          }
          
          const report = await this.client.createAccountReport(createReportArgs);
          return {
            content: [{ type: "text", text: JSON.stringify(report, null, 2) }]
          };
        }
        
        default:
          throw new Error(`Unknown tool: ${toolName}`);
      }
    } catch (error) {
      console.error(`Error executing tool ${request.params.name}:`, error);
      return {
        content: [{
          type: "text",
          text: `Error: ${error instanceof Error ? error.message : String(error)}`
        }],
        isError: true
      };
    }
  });