classmcp

classmcp connects a coding agent to your Google Classroom account through the Model Context Protocol (MCP). It runs on your computer and uses your own Google OAuth Desktop app credentials. There is no hosted classmcp service or telemetry.

You can ask an agent to list upcoming or missing work, find an assignment, download handouts, or prepare a submission. Submission changes are subject to Google's project restriction.

The npm package is named gcrclassmcp; the command is classmcp. You need Node.js 20 or newer and a Google account with access to Classroom.

Install

Install the release candidate from npm:

npm install --global gcrclassmcp@next
classmcp --version

To install from source, clone the repository and install from the project directory:

git clone https://github.com/khurrambhutto/classmcp.git
cd classmcp
npm ci
npm install --global .
classmcp --version

The next tag selects the release candidate. See RELEASE.md for the publication process.

Connect Google Classroom

1. Open Google Cloud Console and create a project.

2. Enable the Google Classroom API and Google Drive API in that project.

3. Configure the OAuth consent screen. Use an External audience for a personal Google account or an Internal audience for an eligible Workspace account. If the app is in Testing, add your account as a test user.

4. Create an OAuth client ID with application type Desktop app. Download its JSON file to your Downloads folder.

5. Run:

   classmcp setup
   

   Setup looks for client_secret*.json in Downloads and asks for a path if it cannot find one. It validates and stores the credentials, opens Google's consent page, verifies Classroom access, and offers to configure detected agent hosts.

6. Run classmcp doctor. Resolve any fail lines. On Windows, review the config folder's access controls as described in Security.

7. Register the server with your agent if setup did not do so. Reconnect or restart the host if needed.

8. Ask your agent to list your courses. A successful get_overview call with view: "courses" confirms that the connection works. An empty course list can be valid for an account with no courses.

Use a dedicated test account while evaluating the server. Never paste your client secret or token files into an agent conversation.

Ask an agent to set it up

You can copy this request into a coding agent with terminal access. Complete Google's browser steps yourself when the agent asks.

Set up the classmcp MCP server from https://github.com/khurrambhutto/classmcp.
The package is gcrclassmcp and the command is classmcp. First read the agent
setup guide at https://khurrambhutto.github.io/classmcp/llms-full.txt (or this
README if you cannot fetch URLs). If you are not Codex, OpenCode, or Claude
Code, read your own host's MCP documentation before registering the server.

1. Check that Node.js is version 20 or newer. If it is not, stop and tell me
   what is missing.
2. Install classmcp using the README's current installation instructions. Run
   classmcp --version to confirm the command is available.
3. If I have not already created Desktop app OAuth credentials, ask me to
   follow the Google Cloud setup in the README. Do not create credentials on
   my behalf or request their contents in chat.
4. Run classmcp setup interactively. Let me approve Google's consent page and
   answer any prompts that require my input.
5. Run classmcp doctor. Explain any failures without printing secrets. On
   Windows, remind me to verify who can access the config folder.
6. Register classmcp with this host using the README's host instructions.
   Preserve existing configuration entries and comments. Do not register a
   temporary npx cache path.
7. Reconnect the server, confirm that all five tools are listed, and call
   get_overview with view="courses". Report whether the call succeeded. An
   empty course list is valid; report the result rather than treating it as an
   error.

Never print or paste credentials, tokens, or their file contents. If a step
fails, report the error and stop instead of inventing a value or result.

Connect an agent

All hosts start classmcp serve over stdio. Use the classmcp executable from a global install, or an absolute path to Node and this repository's dist/cli.js. Do not register a temporary npx cache path.

Codex CLI

codex mcp add classmcp -- classmcp serve
codex mcp list

Alternatively, add this entry to ~/.codex/config.toml:

[mcp_servers.classmcp]
command = "classmcp"
args = ["serve"]
startup_timeout_sec = 30
tool_timeout_sec = 300

OpenCode

Add the entry under mcp in ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "classmcp": {
      "type": "local",
      "command": ["classmcp", "serve"],
      "enabled": true,
      "timeout": 60000
    }
  }
}

Run opencode mcp list and confirm that classmcp is connected. If OpenCode cannot find the executable, use an absolute Node path and the path to dist/cli.js in the command array.

Claude Code

claude mcp add --scope user classmcp -- classmcp serve
claude mcp list

--scope user registers the server for every project. Without it, Claude Code adds the server only for the current directory.

Alternatively, add the following entry under mcpServers in ~/.claude.json:

{
  "mcpServers": {
    "classmcp": {
      "command": "classmcp",
      "args": ["serve"]
    }
  }
}

Cursor and Antigravity

Add an entry under mcpServers in ~/.cursor/mcp.json for Cursor or ~/.config/antigravity/mcp.json for Antigravity:

{
  "mcpServers": {
    "classmcp": {
      "command": "classmcp",
      "args": ["serve"]
    }
  }
}

This is the beginning of the README. Read the rest at the original. Read the full README ↗