SongNgan
Adds Classroom due dates to Google Calendar with reminders before the due time.
Provides tools for accessing Google Classroom courses, assignments, due dates, announcements, materials, grades, people, and submissions.
Enables reading, downloading, and uploading Drive files, including attaching Drive files to Classroom submissions where Google permits it.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
SongNgan
A self-hosted MCP server for Google Classroom.
Let Claude, Cursor, Gemini or any tool-calling AI see your classes, assignments, due dates, attached files and grades.
Install · Install with an AI agent · Tools · Troubleshooting
SongNgan runs on your own computer with your own Google Cloud OAuth client. There is no shared app, no server in between and nothing to pay for. Requests go straight from your machine to Google, and your sign-in token stays in the OS keychain.
What you can ask
"What's due this week?"
"Summarize the Lab 3 instructions for Physics and read the attached PDF."
"Any new announcements from my teachers?"
"Which class has my lowest grade right now?"
"Download the starter notebook for the Machine Learning assignment."
"Put this due date on my Google Calendar."
Related MCP server: mcp-classroom
Install
You need Node.js 20 or later, Git and a Google account that uses Classroom. Setup takes about ten minutes, once.
1. Create a Google OAuth client
Sign in to Google Cloud with any Google account. Each link below opens the right page; make sure your new project is selected at the top of the page.
Create a project, for example
SongNgan.Enable the APIs you need, using Enable on each page:
API
Needed for
Always
Reading, downloading or uploading files
Adding due dates to your calendar
Open Google Auth Platform and choose Get started. Set the app name to
SongNgan, pick your email as the support email, choose the External audience, add your email as the contact and create it.Open Audience and choose Publish app. Without this, Google signs you out every 7 days.
Open Clients and choose Create client. Set the application type to Desktop app, create it, then choose Download JSON. Keep this file private.
2. Build the server
git clone https://github.com/fluki3-06s/songngan-mcp.git
cd songngan-mcp
npm installnpm install also builds the server into dist/index.js.
3. Connect your Google account
npm run setup -- path/to/client_secret.jsonSetup copies the client into ~/.song-ngan/, asks which features to enable and opens Google sign-in in your browser. Google warns that the app is unverified; because the app is your own, choose Advanced > Go to SongNgan. When it finishes, the browser shows this page:
Check the result:
npm run statusGoogle account should show your email and Missing permissions should not appear.
4. Register it with your AI client
Use the absolute path to dist/index.js in the folder you cloned.
{
"mcpServers": {
"song-ngan": {
"command": "node",
"args": ["/absolute/path/to/song-ngan/dist/index.js", "serve"]
}
}
}Client | Where |
Claude Desktop | Settings > Developer > Edit config ( |
Claude Code |
|
Cursor |
|
VS Code |
|
Gemini CLI |
|
LM Studio, Windsurf | the client's |
On Windows, write the path with forward slashes or escaped backslashes, for example "D:/Tools/song-ngan/dist/index.js".
Restart the client and ask: "What's due this week?"
Update
git pull
npm installRestart your AI client afterwards. Your sign-in and settings in ~/.song-ngan/ are kept. If npm run status then shows Missing permissions, the new version needs extra access; run npm run setup once to grant it.
Install with an AI agent
SongNgan can be installed by an AI coding agent such as Claude Code, Cursor or Gemini CLI. Give it this prompt:
Install the SongNgan MCP server for me by following AGENTS.md in https://github.com/fluki3-06s/songngan-mcp.
The agent follows AGENTS.md. It does everything except the steps only you can do: creating the OAuth client in Google Cloud Console and approving the Google sign-in.
Tools
Tools are grouped into features. read is always on; files and write are chosen during setup.
Tool | Feature | Description |
| read | Overdue work, upcoming due dates and recent announcements in one call |
| read | Enrolled classes |
| read | Assignments with status ( |
| read | Full instructions, topic, attached materials, grading rubric and your submission with turn-in time, days late and the history of state and grade changes |
| read | Find assignments, announcements and materials by keyword across classes |
| read | Topics (units or chapters) teachers use to group classwork |
| read | Teachers and classmates in a class |
| read | Teacher announcements |
| read | Materials posted in a class |
| read | Graded work and per-class totals |
| files | Google Docs, Slides, Sheets and Drawings, PDF (scanned pages as images), Word, PowerPoint, Excel, OpenDocument, images, text and code, ZIP listings, video previews |
| files | Save an attached file to |
| files | Web pages, public Google Forms, online PDFs and Office files, YouTube metadata, Drive links |
| write | Upload a local file to Google Drive |
| write | Attach a Drive file to your submission (see note) |
| write | Turn in an assignment; requires |
| write | Add a due date to Google Calendar with reminders 1 day and 1 hour before |
Google only lets an app change submissions for assignments created by that same app. For assignments a teacher created on the Classroom website,attach_to_assignment returns a clear error with a link so you can attach the file yourself.
To change features later, run npm run setup again.
Read tools also return structuredContent with a published outputSchema, so clients and agents get typed JSON instead of parsing text.
Prompts
Ready-made prompts appear in clients that support MCP prompts, for example as slash commands in Claude.
Prompt | Arguments | What it does |
|
| Day-by-day study plan from overdue and upcoming work |
|
| Summarizes an assignment and its materials into a checklist of deliverables |
|
| Reviews your draft against the rubric or instructions before you turn it in |
Resources
Clients that support MCP resources can attach Classroom data to a chat directly.
URI | Content |
| Your active classes |
| One class with all of its assignments |
| One assignment with materials, rubric and submission; open work is listed for quick picking |
CLI
Run from the cloned folder with node dist/index.js <command>.
Command | Description |
| Connect a Google account and choose features |
| Sign-in state, enabled features and storage location |
| Revoke access at Google and delete the local token |
| Print tool schemas ( |
| Run a tool from the terminal |
| Start the MCP server over stdio |
Configuration
Variable | Description |
| Config folder, default |
| Path to |
| Comma-separated features, e.g. |
|
|
| Set to |
Troubleshooting
Problem | Fix |
| Run |
| Your school blocks third-party apps. Ask IT to allow it. |
| Access was not approved, or the app is still in testing mode. Publish it under Audience. |
| Enable that API in your Google Cloud project. |
Signed out every 7 days | The app is in testing mode. Publish it under Audience. |
| Run |
The AI client does not list the tools | Check the absolute path to |
Cannot attach a file to an assignment | A Google limit, see the note under Tools. Attach it from the returned link. |
Privacy and security
Everything runs locally under your own OAuth client. There is no SongNgan server and no telemetry.
client_secret.jsonis copied to~/.song-ngan/. Never commit it.The refresh token is stored in the OS keychain (macOS Keychain, Windows Credential Manager, libsecret). Without a keychain it falls back to
~/.song-ngan/token.jsonwith0600permissions.Scopes are requested per feature, and write access is off by default.
node dist/index.js logoutrevokes the token at Google and deletes it locally.
Feature | Scopes |
read |
|
files |
|
write |
|
Development
npm run check # typecheck, lint, format check and tests
npm run format # apply Prettier
npm run build
npm run inspect # MCP Inspector against dist/index.jssrc/
├── core/
│ ├── google/ Classroom, Drive and Calendar gateways
│ ├── readers/ File and link readers
│ ├── tools/ Tool base class, read, file and write tools, registry
│ ├── study.ts Assignments, search, topics, people, digest and grades
│ └── ... Config, auth, token store, cache, retry
├── adapters/ MCP server (tools, prompts, resources) and JSON schema export
├── cli/ Commands and terminal UI
├── application.ts Composition root
├── index.ts CLI entry
└── lib.ts Library entryTo add a tool, extend Tool in src/core/tools/, register it in ToolRegistry.catalog() and add a test. See CONTRIBUTING.md for the full workflow and CHANGELOG.md for release notes.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to access and interact with Google Classroom data, allowing users to view courses, course details, and assignments through natural language commands.7MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for Google Classroom enabling reading assignments, checking submission states, uploading files to Drive, and viewing attachments, with optional Playwright automation for write operations restricted by Workspace admins.-
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP server for managing Google Workspace services (Gmail, Calendar, Drive, Docs, Sheets, Slides) through natural language with AI assistants like Claude and Cursor.33 npm1MIT
- AlicenseAqualityDmaintenanceUnified MCP server for Google Classroom, Drive, and Docs, enabling AI assistants to manage courses, assignments, files, and documents.17MIT