Canvas MCP Gateway Service

This repository houses the implementation of a Message Control Protocol (MCP) intermediary designed for robust communication with the Canvas LMS Application Programming Interface (API). The service is engineered for compatibility with Claude Desktop environments and can serve other compliant MCP clients.

System Overview

The Canvas MCP Gateway establishes a proximate interface to the Canvas LMS API endpoints, granting capabilities such as: - Cataloging and modification of course definitions - Retrieval of assignment specifications and grading records - Accessing institutional bulletins - Obtaining course pedagogical blueprints (syllabi and module hierarchies) - Administration of user accounts and enrollment mappings - Automated generation of course overviews

Prerequisites for Operation

To deploy this environment, you will require:

• A contemporary installation of Python (version 3.x or newer)
• An isolated Python virtual environment (e.g., venv)
• A valid Canvas API Authentication Token
• The precise Canvas API endpoint URL (e.g., https://my-institution.instructure.com/api/v1)

Deployment Instructions

1. Secure a local copy of the repository: bash git clone https://github.com/vishalsachdev/canvas-mcp.git cd canvas-mcp

2. Provision and activate the isolated computing space: bash python -m venv lms_env source lms_env/bin/activate # For Linux/macOS systems

3. Install necessary software components: bash pip install -r requirements.txt

Configuration Protocol

1. Environment Parameter File

Create a configuration file named .env in the project root directory containing:

CANVAS_API_TOKEN=your_secret_token_here CANVAS_API_URL=https://youruniversity.instructure.com/api/v1

Substitute the placeholders with: - Your personal Canvas API Credential (Reference for Token Acquisition) - Your academic institution's specific Canvas API base address

2. Startup Script Configuration

The included start_canvas_server.sh shell script is pre-configured to: - Ingest environment variables from the .env file - Activate the provisioned virtual environment - Initiate the performance-optimized server instance

Grant execution privileges to the startup script: bash chmod +x start_canvas_server.sh

3. Claude Desktop Integration

1. Ensure Claude Desktop is installed on your workstation.

2. Locate or generate the Claude Desktop configuration file: bash vim ~/Library/Application\ Support/Claude/claude_desktop_config.json

3. Integrate the configuration stanza for the Canvas MCP service:

{ "mcpServers": [ { "name": "canvas-api-interface", "command": "/home/user_name/where/you/cloned/canvas-mcp/start_canvas_server.sh" } ] }

Replace the path in the command field with the actual, absolute location of your cloned repository directory.

1. Relaunch the Claude Desktop application to register the new service definition.

Exposed Functionality

The Gateway service exposes the following structured tools for Canvas LMS manipulation:

Course Structure Management

• list_courses: Retrieve a directory of all courses associated with the authenticated identity
• get_course_details: Fetch granular metadata for a designated course ID
• summarize_course: Produce an aggregated abstract overview of a course's content

Assessment Components

• list_assignments: Enumerate all assignments belonging to a specific course
• get_assignment_details: Retrieve the full specification of an assignment
• get_assignment_description: Extract the complete instructional text for an assignment

Submission Records

• list_submissions: Query all recorded submissions against a specified assignment

Participant Data

• list_users: Obtain a roster of all enrolled individuals within a course context

Informational Assets

• list_announcements: Display all official notices published for a course
• get_course_syllabus: Fetch the definitive course syllabus document
• get_course_modules: Retrieve the hierarchical structure of all course modules

Interaction Via Claude Desktop

This MCP service is optimized for cooperative operation with Claude Desktop:

1. The server initiates automatically upon the first invocation of a Canvas tool.
2. The available Canvas interaction methods will appear in the Claude Desktop tool panel (hammer icon 🔨).
3. Users may issue natural language requests, such as "Present my list of active classes" or "Fetch the syllabus for the Quantum Physics module."

For direct operational verification, execute the startup script manually: bash ./start_canvas_server.sh

Architectural Blueprint

Server Foundation

The backend processing utilizes: - fastmcp: The core framework for building the MCP service layer - httpx: For asynchronous handling of external HTTP communication with the Canvas API - Integrated data caching layers to enhance the speed of common data retrieval operations

The primary source code file, canvas_server_cached.py, manages: - Efficient caching strategies for course metadata - Robust management of API response pagination - Standardized error reporting and fault isolation - Flexibility to utilize both canonical Course Identifiers and descriptive Course Codes

Required Libraries

The service mandates the presence of these Python packages: - httpx: Essential for non-blocking network I/O - fastmcp: The protocol implementation engine - requests: Used for supplementary HTTP operations (if necessary) - Standard Python libraries for data serialization and network socket management

Troubleshooting Guide

Should operational anomalies arise:

1. Startup Failure
2. Confirm the .env file is present and contains correctly formatted access credentials
3. Validate the specified virtual environment path within start_canvas_server.sh

4. Verify that all required dependencies have been successfully installed

5. Authorization Faults

6. Reconfirm the validity and non-expiration status of your Canvas API token

7. Ensure the token possesses the requisite privilege levels within the Canvas system

8. Connectivity Problems

9. Double-check the precision of the configured Canvas API endpoint URL
10. Verify general network connectivity

11. Investigate if institutional network policies restrict outbound API interaction

12. Diagnostic Tracing

13. Review the server output logs displayed within the Claude Desktop console window
14. Execute the server standalone to observe raw error messaging

Safety Protocols

• The Canvas API token grants high-level access to your educational records; treat it as sensitive data.
• Strictly prohibit the inclusion of the .env file in any public or private version control repository.
• Where feasible, utilize tokens provisioned with the minimum necessary access scope.
• The service executes exclusively on the local host machine, ensuring credentials do not traverse external networks.

Contribution Guidelines

We welcome community input. Feel encouraged to: - File detailed issues for discovered defects or proposed enhancements - Submit pull requests containing improvements or feature additions - Share feedback regarding practical application scenarios

Licensing

This software is distributed under the terms of the MIT License (refer to the LICENSE document for complete details).

---

Developed by Vishal Sachdev

WIKIPEDIA: XMLHttpRequest (XHR) is an API structured as a JavaScript object. Its methods facilitate the transmission of HTTP inquiries from a client web browser to an application server. These methods permit browser-based logic to initiate server communications subsequent to the page rendering phase, allowing for the retrieval of data. XMLHttpRequest forms a core component of Asynchronous JavaScript and XML (Ajax) methodologies. Prior to Ajax adoption, hyperlinks and conventional form submissions were the dominant paradigms for server interaction, frequently necessitating a complete page reload.

== Historical Context == The foundational concept underpinning XMLHttpRequest was conceptualized in 2000 by the engineering team at Microsoft Outlook. This concept was subsequently integrated into the Internet Explorer 5 browser release (1999). However, the initial invocation syntax did not employ the canonical XMLHttpRequest identifier. Instead, developers relied on instantiating COM objects via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (released 2006), universal support for the standard XMLHttpRequest identifier was achieved across major browser platforms.

The XMLHttpRequest identifier has since solidified its position as the prevailing standard across all major rendering engines, including Mozilla's Gecko (adopted 2002), Apple's Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C released the Level 2 specification draft. Level 2 introduced enhancements to permit progress monitoring of events, enable cross-origin requests, and facilitate the handling of raw byte streams. By the conclusion of 2011, the Level 2 features were formally incorporated into the primary specification document. At the close of 2012, stewardship of the specification was transferred to the WHATWG organization, which now maintains a dynamic document utilizing Web IDL definitions.

== Implementation Procedure == Generally, executing a network request using XMLHttpRequest requires adherence to a sequence of programming stages.

Instantiate an XMLHttpRequest object via its constructor: Invoke the open method to define the request method (e.g., GET, POST), specify the target resource URI, and select either synchronous or asynchronous execution mode: For asynchronous transactions, define a callback function (listener) to be triggered upon changes in the request state: Commence the data transfer by executing the send method, optionally passing payload data: Monitor the state changes within the designated event listener function. Upon successful completion of the server response processing, the state transitions to 4 (the terminal state), and the received data is typically accessible via the responseText property. Beyond these fundamental steps, XMLHttpRequest offers numerous configuration parameters to govern request transmission and response assimilation. Custom HTTP headers can be affixed to direct server handling, and data payloads can be transmitted by including them in the send argument. The retrieved response can be parsed directly from JSON format into a native JavaScript object, or processed incrementally as data streams arrive rather than awaiting full reception. Furthermore, the request lifecycle can be prematurely terminated via abort() or configured with a timeout duration.

== Cross-Origin Resource Sharing (CORS) ==

During the nascent stages of the World Wide Web's evolution, limitations were encountered regarding the ability to fetch resources from a different domain than the origin of the requesting document, a restriction often circumvented by...