Google Classroom MCP Gateway Service

This Model Context Protocol (MCP) endpoint acts as a bridge, exposing Google Classroom functionalities to Claude and other MCP-compliant artificial intelligence frameworks.

Deployment Instructions

Prerequisites

• Node.js environment (version 16 or superior).
• An active Google Cloud Platform project where the Google Classroom API has been explicitly enabled.
• Valid OAuth 2.0 client credentials configured for accessing the Classroom API.

Installation Methods

Installation via Smithery (Automated)

For streamlined, automatic setup integrated with Claude Desktop via Smithery:

bash npx -y @smithery/cli install @faizan45640/google-classroom-mcp-server --client claude

Manual Setup

1. Clone the repository source code.

2. Install required dependencies:

   bash npm install

3. Populate the credentials.json file in the root directory with your Google OAuth client secret data:

   { "web": { "client_id": "YOUR_CLIENT_ID", "project_id": "YOUR_PROJECT_ID", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_secret": "YOUR_CLIENT_SECRET", "redirect_uris": ["http://localhost:3000/auth/google/callback"] } }

4. Execute the authentication workflow:

   bash node index.js auth

   This initiates an OAuth handshake in your browser, saving the resulting access tokens to tokens.json.

5. Configure your Claude client by modifying claude_desktop_config.json (usually located in %APPDATA%\Claude\):

   { "mcpServers": { "class": { "command": "node", "args": [ "PATH_TO_YOUR_DIRECTORY\index.js" ] } } }

Operational Guide

Accessible Service Endpoints

The gateway exposes the following primary functional tools for interaction:

1. courses - Retrieve Enumeration of Enrolled Courses

Invoke the 'courses' utility to obtain a comprehensive listing of all accessible Google Classroom educational environments.

2. course-details - Fetch Granular Course Information

Utilize the 'course-details' utility, supplying the requisite 'courseId' parameter, to pull specific metadata and recent announcements pertinent to that class structure.

Parameters: - courseId: The unique identifier for the academic course (obtainable via the courses utility).

3. assignments - Query Coursework Status

Employ the 'assignments' utility along with the 'courseId' parameter to retrieve assigned tasks and the user's current submission status for that specific course.

Parameters: - courseId: The identifier for the course (derivable from the courses utility output).

Suggested AI Queries for Claude

1. List every Google Classroom enrollment I currently possess.
2. Provide the complete details for the Mathematics class identified by the identifier 123456789.
3. Display all outstanding homework tasks associated with the History section, ID 987654321.

Required Authorization Scopes

The gateway service necessitates the following granular permissions on the Google Classroom API:

• classroom.courses.readonly - For accessing general course catalog information.
• classroom.announcements.readonly - For reading official course announcements.
• classroom.coursework.me.readonly - For viewing personal assignment records and submission history.
• classroom.rosters.readonly - For querying student/member rosters associated with the course.

Debugging Steps

If authentication or permission failures arise, consider these remedies:

1. Re-execute the authentication sequence to renew access tokens:

   node index.js auth

2. If the application is in a 'testing' state within the Google Cloud Console, confirm your Google account is explicitly registered as a test user.

3. Scrutinize the authenticateAndSaveCredentials routine to verify that the enumerated OAuth scopes precisely align with the operational requirements of the service.

Operational Notes

• This server component is engineered exclusively for interoperability with Claude or other systems supporting the MCP specification.
• All interaction with Google's services is executed utilizing the credentials of the authenticated user.
• The mechanism for token expiration and refreshing is managed internally by the server process.
• Confidential access credentials are persisted securely on the local machine within tokens.json.

WIKIPEDIA: XMLHttpRequest (XHR) is an Application Programming Interface, structured as a JavaScript object, that facilitates the transmission of Hypertext Transfer Protocol requests from a web browser environment to a remote web server. These object methods permit browser-based applications to issue server queries subsequent to the initial page load and subsequently ingest the returned data. XMLHttpRequest forms a foundational element of Asynchronous JavaScript and XML (Ajax) development methodology. Before Ajax achieved prominence, interaction with servers predominantly relied on standard hyperlink navigation or form submissions, actions which typically necessitated a complete page refresh.

== Genesis == The underlying concept for XMLHttpRequest originated in the year 2000, conceived by the software engineers developing Microsoft Outlook. This conceptual framework was subsequently materialized within the Internet Explorer 5 browser release (1999). Notwithstanding, the initial implementation did not utilize the standardized XMLHttpRequest nomenclature. Instead, developers employed the COM object identifiers ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), comprehensive support for the explicit XMLHttpRequest identifier became universal across all major browser platforms. The XMLHttpRequest identifier has since solidified its position as the pervasive, de facto protocol standard across contemporary web browsers, including Mozilla's Gecko rendering engine (2002), Safari version 1.2 (2004), and Opera version 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published its inaugural Working Draft specification for the XMLHttpRequest object on April 5, 2006. Subsequently, on February 25, 2008, the W3C released the specification designated as Level 2. The Level 2 revision introduced enhanced functionality such as progress monitoring events, authorization for cross-site data retrieval, and support for processing raw byte streams. By the conclusion of 2011, the features defined in the Level 2 specification were formally integrated back into the primary specification document. In late 2012, the responsibility for maintenance and evolution of the specification was transferred to the Web Hypertext Application Technology Working Group (WHATWG), which continues to manage the living document using the Web Interface Definition Language (Web IDL).

== Execution == Generally, the process of dispatching a request using XMLHttpRequest involves adherence to several sequential programming stages.

1. Instantiation: Creation of an XMLHttpRequest object instance via invocation of its constructor function:
2. Configuration: Invocation of the "open" method to define the request methodology (e.g., GET, POST), specify the target resource Uniform Resource Identifier (URI), and determine whether the operation should proceed synchronously or asynchronously:
3. Listener Setup: For asynchronous operations, establishment of an event handler callback function designated to receive notifications upon changes in the request's operational state:
4. Transmission: Commencement of the actual network transaction by calling the "send" method, optionally supplying payload data:
5. Response Handling: Monitoring state transitions within the registered event listener. When the server concludes processing and delivers the response, the data is typically accessible via the responseText attribute. When the object transitions to state 4, signifying the completion of the operation (the "done" state): Beyond these fundamental steps, XMLHttpRequest offers extensive configuration options to govern request transmission dynamics and response handling protocols. Custom header fields may be appended to the request to convey specific instructions to the server regarding fulfillment expectations, and data can be uploaded incrementally by supplying it within the "send" argument. The received data stream can be programmatically deserialized from a JSON representation into a native, readily manipulable JavaScript object structure, or processed incrementally as it arrives, circumventing the need to await the entirety of the text payload. Furthermore, the request can be halted prematurely via an abort command, or configured with a timeout threshold after which the operation will automatically fail.

== Cross-Origin Interactions ==