Canvas MCP Server V2.0

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/index.ts:650-658 (registration)

  Tool registration in TOOLS array, defining name, description, and empty input schema.
  { name: "canvas_list_conversations", description: "List user's conversations", inputSchema: { type: "object", properties: {}, required: [] } },
• src/client.ts:505-508 (handler)

  Core implementation of canvas_list_conversations tool: calls Canvas API GET /conversations endpoint and returns the list of conversations.
  async listConversations(): Promise<CanvasConversation[]> { const response = await this.client.get('/conversations'); return response.data; }
• src/index.ts:651-657 (schema)

  Input schema definition for the tool (empty object, no parameters required).
  name: "canvas_list_conversations", description: "List user's conversations", inputSchema: { type: "object", properties: {}, required: [] }
• src/types.ts:423-443 (schema)

  TypeScript interface defining the structure of Canvas conversation objects returned by the tool.
  export interface CanvasConversation { id: number; subject: string; workflow_state: 'read' | 'unread' | 'archived'; last_message: string; last_message_at: string; last_authored_message: string; last_authored_message_at: string; message_count: number; subscribed: boolean; private: boolean; starred: boolean; properties: string[]; audience: number[]; audience_contexts: { [key: string]: string[]; }; avatar_url: string; participants: CanvasConversationParticipant[]; messages?: CanvasConversationMessage[]; }
• src/index.ts:1076-1464 (handler)

  MCP server handler dispatch for tool calls. The switch statement routes 'canvas_list_conversations' to client.listConversations() and formats response as MCP content.
  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 }; } });