Canvas LMS Data Connector (MCP Implementation)

This repository provides a streamlined Machine Conversation Protocol (MCP) gateway tailored for effortless access to educational data housed within your designated Canvas LMS environment. It acts as a vital intermediary layer connecting advanced AI agents (like Cursor) to the core features of the Canvas Learning Management System.

Core Capabilities

• Retrieve and enumerate scheduled tasks (e.g., submissions, tests).
• Fetch details and listings for course assignments.
• Obtain and list associated course assessments/quizzes.
• Query and enumerate active course enrollments.
• Access and retrieve specified course syllabi.
• Fetch hierarchical structures of course learning modules.
• List content assets within file repositories.

Deployment Instructions

Automated Deployment via Smithery

To facilitate rapid setup for Claude Desktop integration using Smithery, execute the following command:

bash npx -y @smithery/cli install @ahnopologetic/canvas-lms-mcp --client claude

Essential Prerequisites

• Runtime environment: Python version 3.13 or newer.
• Authentication credential: A valid Canvas LMS API access token.
• Dependency manager: uv is strongly recommended for package handling.

Installation Pathways

Method 1: Utilizing uvx (Preferred)

Executing uvx offers the most straightforward path to run canvas-lms-mcp in an ephemeral, sandboxed environment:

bash uvx canvas-lms-mcp

For persistent installation across environments:

bash uv tool install canvas-lms-mcp

Method 2: Compilation from Source

1. Clone the repository location: bash git clone https://github.com/yourusername/canvas-lms-mcp.git cd canvas-lms-mcp

2. Manage dependencies with uv: bash # Install uv if missing curl -LsSf https://astral.sh/uv/install.sh | sh

   Establish isolated environment and install required packages

   uv venv uv pip install -e .

   Alternatively, employ conventional Python tooling: bash python -m venv .venv source .venv/bin/activate # For Windows: .venv\Scripts\activate pip install -e .

Configuration Requirements

Ensure the following environmental variables are accurately defined:

bash export CANVAS_API_TOKEN="your_actual_canvas_api_token" export CANVAS_BASE_URL="https://your-institution.instructure.com" # Override default: https://canvas.instructure.com

Your API token can be generated within the personal settings area of your Canvas account interface.

Server Execution

Initiate the service process using uv:

bash uv run src/canvas_lms_mcp/main.py

If deployed via the uv tool installer: bash canvas-lms-mcp

The service defaults to listening on port 8000 (http://localhost:8000). Comprehensive API interaction documentation is available at http://localhost:8000/docs (FastMCP interface).

Exposed Functionality (Tools)

The server exposes the following atomic operations for Canvas LMS data interaction:

Course Management

list_courses

Retrieves a paginated enumeration of courses the authenticated user is currently registered within.

Parameters: - page (optional, default=1): The index of the results page (starting from 1). - items_per_page (optional, default=10): Quantity of records per result page.

get_course

Fetches detailed information for a specific course identified by its unique ID.

Parameters: - course_id (required): The numeric identifier for the course. - include (optional): Specification for supplementary data inclusion in the response.

get_course_syllabus

Retrieves the published syllabus document associated with a given course.

Parameters: - course_id (required): The course identifier.

get_course_modules

Fetches the hierarchical structure of learning modules pertaining to a course.

Parameters: - course_id (required): The course identifier. - include (optional): Specification for supplementary data inclusion.

Assignment Operations

list_assignments

Provides a filtered and ordered listing of assignments relevant to a specified course.

Parameters: - course_id (required): The identifier of the course. - bucket (required): Criteria for filtering results (e.g., "upcoming", "ungraded", "past"). - order_by (required): Metric for sorting results ("due_at", "position", or "name"). - page (optional, default=1): Page number. - items_per_page (optional, default=10): Results quantity per page.

get_assignment

Retrieves the specifics of an assignment identified by its ID within a course context.

Parameters: - course_id (required): The course identifier. - assignment_id (required): The unique assignment identifier.

Quiz Management

list_quizzes

Lists available quiz assessments for a specific course.

Parameters: - course_id (required): The course identifier. - include (optional): Data inclusion directives. - page (optional, default=1): Page index. - items_per_page (optional, default=10): Items per response page.

get_quiz

Retrieves the data for an individual quiz.

Parameters: - course_id (required): The course identifier. - quiz_id (required): The unique quiz identifier.

Asset Retrieval (Files)

list_files

Enumerate content files accessible within a course or a specific directory structure.

Parameters: - course_id (optional): Contextual course identifier. - folder_id (optional): Identifier for the target directory. - include (optional): Data inclusion directives. - page (optional, default=1): Page index. - items_per_page (optional, default=10): Items per page.

User Schedule Items

list_planner_items

Retrieves items from the authenticated user's organizational planner spanning a specified date range.

Parameters: - start_date (required): Initial date for query, expressed in ISO 8601 standard. - end_date (required): Terminal date for query, expressed in ISO 8601 standard. - context_codes (optional): List filtering results by context (e.g., specific course IDs). - page (optional, default=1): Page index. - items_per_page (optional, default=10): Results per page.

Integration with Cursor IDE

Cursor, an AI-enhanced integrated development environment, is capable of leveraging this Canvas MCP server to directly query educational data within your workflow.

Setting up Cursor Interoperability

1. Obtain and install the Cursor IDE from https://cursor.sh/

2. Establish a configuration file named .cursor/mcp.json within your active project root, populated with the following structure:

   { "mcpServers": { "canvas": { "command": "uvx", "args": [ "canvas-lms-mcp" ], "env": { "CANVAS_API_TOKEN": "your_canvas_api_token", "CANVAS_BASE_URL": "https://your-institution.instructure.com" } } } }

   Note: Substitute placeholders with your actual API key and institutional domain URL.

3. Apply the changes by restarting the Cursor application.

Optional: Timezone Synchronization

To support time-sensitive queries, an auxiliary time server can be integrated into mcp.json:

"time": { "command": "uvx", "args": [ "mcp-server-time", "--local-timezone=America/New_York" ] }

This permits the use of accurate temporal functions alongside your Canvas data requests.

Usage Scenarios

Once the connection is active, natural language queries directed at Cursor can target your Canvas data:

• "What deliverables are scheduled for submission next week?"
• "Display the course outline for my advanced Physics class."
• "List all impending assessment sessions."
• "Summarize my schedule for the forthcoming 24 hours."

Illustrative Exchange:

USER: Which tasks are approaching their deadline?

CURSOR: Analyzing imminent deadlines from your Canvas records...

Based on the retrieved data, here are your imminent tasks: - "Capstone Project" (Course CS101) due 2023-12-10 - "Laboratory Report #5" (Course BIOL200) due 2023-12-07 - "Scholarly Article" (Course ENGL301) due 2023-12-15

Development Roadmap

For comprehensive documentation regarding source code contribution and local development setup, consult the DEVELOPMENT.md document.

Licensing

This software is distributed under the terms of the MIT License. Full details are available in the LICENSE file.

---

WIKIPEDIA CONTEXT: XMLHttpRequest (XHR) is an API embodied as a JavaScript object, designed to facilitate the transmission of HTTP requests from a web client to a remote server. Its methods permit client-side scripting to dispatch requests post-page-load and asynchronously receive data. XHR forms a foundational pillar of Ajax programming methodology. Before Ajax, server interaction relied primarily on full-page refreshes triggered by form submissions or hyperlink navigation.

== Chronology == The underlying concept for XMLHttpRequest originated in 2000 through the efforts of Microsoft Outlook developers. This notion was first implemented in Internet Explorer version 5 (released in 1999). However, the inaugural implementation utilized COM object identifiers like ActiveXObject("Msxml2.XMLHTTP") rather than the standardized XMLHttpRequest identifier. By the release of Internet Explorer 7 (2006), full compliance with the universal XMLHttpRequest identifier was established across all major browser platforms, including Mozilla’s Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) issued the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Level 2 specification draft followed on February 25, 2008, introducing capabilities such as progress monitoring, cross-site request facilitation, and byte stream handling. By late 2011, the Level 2 features were merged back into the primary specification. Development transitioned to the WHATWG consortium starting in 2012, which now maintains the living document using Web IDL definitions.

== Operation == Generally, dispatching a request via XMLHttpRequest requires adherence to several sequential programming phases:

1. Instantiation: Create an XMLHttpRequest object instance via its constructor.
2. Setup: Invoke the open method to define the HTTP verb, specify the target resource URI, and select between synchronous or asynchronous execution mode.
3. Asynchronous Listener (if applicable): For asynchronous calls, attach an event handler to monitor state transitions.
4. Transmission: Trigger the request delivery using the send method, optionally passing payload data.
5. Response Handling: Process state changes within the event listener. Upon completion (state 4, "done"), response content is typically accessible via the responseText property.

Beyond these core steps, XHR offers extensive control over request mechanics and response processing. Custom HTTP headers can be set to guide server behavior. Upload data can be transmitted within the send call. Received data can be parsed immediately from JSON into native JavaScript objects or handled incrementally as the stream arrives. Furthermore, requests can be prematurely terminated or subjected to time-out constraints.