Google Classroom MCP Server

A Model Context Protocol (MCP) server for Google Classroom integration, designed to be run via npx in environments like n8n, claude desktop, Cline... . This server enables AI assistants to manage Google Classroom entities such as courses, announcements, topics, and coursework.

Features

• List Google Classroom courses.
• Create announcements in a specified course, now supporting attachments.
• Create topics within a course.
• Create coursework (assignments) with due dates, descriptions, and now supporting attachments.
• Create coursework material, now supporting attachments.
• Retrieve comprehensive details for a specific course (topics, coursework, materials, students).
• Secure OAuth2 authentication using pre-generated refresh tokens.

Setup for npx Execution (e.g., in n8n Cloud)

To use this MCP server when hosted (e.g., via npx in n8n cloud), you need to provide Google Cloud credentials and a pre-generated refresh token as environment variables.

1. Create a Google Cloud Project and Obtain OAuth 2.0 Credentials:

a. Create/Select a Google Cloud Project: - Go to the Google Cloud Console. - Create a new project or select an existing one.

b. Enable the Google Classroom API: - In your Google Cloud Project, navigate to "APIs & Services" > "Library". - Search for "Google Classroom API" and "Google Drive API" and enable them.

c. Create OAuth 2.0 Client ID: - Go to "APIs & Services" > "Credentials". - Click "+ CREATE CREDENTIALS" > "OAuth client ID". - For "Application type", select "Web application" (this type is suitable for OAuth playground Guide For OAuth playground). - Give it a name (e.g., "Classroom MCP "). - Important: Under Authorized redirect URIs, add a line with: https://developers.google.com/oauthplayground - Click "CREATE". - Also Important: Copy the Client ID and Client Secret. You will need these for the next step and for environment variables. - YOUR_GOOGLE_CLIENT_ID - YOUR_GOOGLE_CLIENT_SECRET

2. Obtain a Refresh Token using OAuth 2.0 Playground:

a. Go to the Google OAuth 2.0 Playground.

b. Click the gear icon (OAuth 2.0 configuration) in the top right. - Check the box "Use your own OAuth credentials". - Enter the YOUR_GOOGLE_CLIENT_ID into "OAuth Client ID". - Enter the YOUR_GOOGLE_CLIENT_SECRET into "OAuth Client secret". - Click "Close".

c. Authorize APIs (Step 1 on Playground): - In the "Input your own scopes" text box at the bottom of the list, paste all the following Google Classroom API scopes, separated by spaces: https://www.googleapis.com/auth/classroom.courses.readonly https://www.googleapis.com/auth/classroom.announcements https://www.googleapis.com/auth/classroom.rosters.readonly https://www.googleapis.com/auth/classroom.profile.emails https://www.googleapis.com/auth/classroom.coursework.students https://www.googleapis.com/auth/classroom.courseworkmaterials https://www.googleapis.com/auth/classroom.topics https://www.googleapis.com/auth/classroom.student-submissions.students.readonly https://www.googleapis.com/auth/classroom.coursework.me https://www.googleapis.com/auth/classroom.addons.teacher https://www.googleapis.com/auth/drive - Click the "Authorize APIs" button. - Sign in with the Google account that has access to the Google Classroom(s) you want to manage. - Grant the requested permissions. You will be redirected back to the Playground.

d. Exchange Authorization Code for Tokens (Step 2 on Playground): - You should see an "Authorization code" filled in. - Click the "Exchange authorization code for tokens" button. - On the right side (Step 3), you will now see a Refresh token and an Access token. - Important: Copy the Refresh token. This is YOUR_GOOGLE_CLASSROOM_REFRESH_TOKEN. - Note: If you add new scopes later (e.g., for new tools), you will need to repeat this authorization process to grant the application the new permissions.

3. Configure Environment Variables in Your Execution Environment (e.g., n8n Cloud):

When setting up the MCP client node in n8n (or any other environment that will execute this MCP via npx), you need to configure the following environment variables:

• GOOGLE_CLIENT_ID: Your OAuth Client ID from step 1c.
• GOOGLE_CLIENT_SECRET: Your OAuth Client Secret from step 1c.
• GOOGLE_CLASSROOM_REFRESH_TOKEN: The Refresh Token you obtained from the OAuth 2.0 Playground in step 2d.
• DOWNLOAD_DIR: The desired directory to download attatchments. For example, "C:\Users\Admin\Desktop"

4. Configure the MCP Client Node in n8n:

• Command: npx
• Arguments: [@your-npm-username/google-classroom-mcp] (Replace with your actual published package name)
• Environment Variables: Set the three variables listed above.
• NOTE: Maybe it doesnt work in n8n. If you host it locally in the args you should put command "node" instead of "npx" and the path to the clonned repo.

Provided MCP Tools

This server provides the following tools for interacting with Google Classroom:

• list_courses: Lists all Google Classroom courses the authenticated user has access to.
• create_announcement: Creates an announcement in a specified course.
  • Inputs: courseId, text, materials (optional)
• create_topic: Creates a new topic in a specified course.
  • Inputs: courseId, name
• create_coursework: Creates new coursework (e.g., an assignment).
  • Inputs: courseId, title, description (optional), materials (optional), state (optional), dueDate (optional), dueTime (optional), maxPoints (optional), workType (optional), topicId (optional), individualStudentsOptions (optional), assigneeMode (optional).
• create_courseworkmaterial: Creates new coursework material in a specified Google Classroom course.
  • Inputs: courseId, title, description (optional), materials (optional), state (optional), topicId (optional).
• edit_element: Edits an existing announcement, topic, coursework, coursework material.
  • Inputs: courseId, entityType (announcement, topic, coursework, courseworkmaterial, announcement_attachment, coursework_attachment, courseworkmaterial_attachment), entityId, attachmentId (required for attachment entity types), fieldsToUpdate (object of fields to update).
• get_course_details: Retrieves details for a specific course.
  • Inputs: courseId
  • Outputs: topics, courseWork, courseWorkMaterials, students, lastAnnouncementId, lastAnnouncementText.
• get_coursework_details: Retrieves details for a specific coursework, including submissions, rubrics, and general information.
  • Inputs: courseId, courseWorkId, studentId (optional)
• download_attachments: Downloads one or more Classroom attachments by their Drive file IDs. This tool is now smarter: it will download binary files (like images, zip files) directly, but it will automatically export Google Workspace files (Docs, Sheets, Slides) to PDF format, ensuring you always get a usable file.
  • Inputs: fileIds (array of strings), downloadPath (optional)
• read_attachment: Reads the content of a Google Workspace file (Doc, Sheet, Slide) by exporting it as plain text. For other files, it returns a message indicating they should be downloaded. This is the most direct way to get the content of a document without saving it locally. Inputs:fileId (string)
• add_comment: Adds a comment to a specific file in Google Drive.
  • Inputs: fileId (string), content (string), quotedText (string, optional)

Typical Workflow Example

Here is a common workflow for interacting with a student's submitted assignment:

1. Discover Files: Use the get_coursework_details tool to see what files a student has submitted for an assignment. This will give you the fileId and mimeType for each attachment.

   {
     "tool_name": "get_coursework_details",
     "arguments": {
       "courseId": "788745376729",
       "courseWorkId": "788745351727"
     }
   }

2. Read Content: If an attachment is a Google Doc (application/vnd.google-apps.document), use the read_attachment tool with its fileId to read its content directly.

   {
     "tool_name": "read_attachment",
     "arguments": {
       "fileId": "1VjyrnSSNsgxgicVXuxXHibKIGdHFadI2Oh_i_2Hz_lA"
     }
   }

3. Download a Local Copy: To get a local PDF copy of the same file, use the download_attachments tool.

   {
     "tool_name": "download_attachments",
     "arguments": {
       "fileIds": ["1VjyrnSSNsgxgicVXuxXHibKIGdHFadI2Oh_i_2Hz_lA"]
     }
   }

4. Add a Comment: After reviewing the content, add a comment directly to the student's file.

   {
     "tool_name": "add_comment",
     "arguments": {
       "fileId": "1VjyrnSSNsgxgicVXuxXHibKIGdHFadI2Oh_i_2Hz_lA",
       "content": "Great job on the introduction! Please remember to cite your sources in the next draft.",
       "quotedText": "Hi this is a test"
     }
   }

Development

(Add details about local development, building, etc., if you wish to keep the interactive auth for local testing)

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Run locally (if you adapt cli.ts or server.ts to support local token generation/use)
# npm start

Security Notes

• Keep your Google API Client ID, Client Secret, and especially the Refresh Token secure.
• The Refresh Token provides long-term access to the authorized Google Classroom data. Treat it like a password.
• Do not commit these credentials directly into your version control. Use environment variables as described.