ClassDojo Roster MCP

An unofficial, local-first Model Context Protocol (MCP) server for teachers who need to inspect Excel/XLSX student rosters, preview changes, import students into ClassDojo, and verify the saved roster afterward. It works with any MCP client that can launch a local stdio server, including Claude Desktop, Codex, Cursor, and VS Code.

繁體中文文件：docs/README.zh-TW.md

Why this MCP server exists

ClassDojo's bulk paste flow can interpret a leading number as list numbering instead of part of a student's display name. This server keeps roster changes reviewable and supports two explicit formats:

• seat_number_dot_name: creates names such as 1.Student A one at a time so the seat number is preserved.

• name_only: uses ClassDojo's faster bulk paste flow when seat numbers are not needed; it is rejected if a source class contains duplicate names.

Every write requires a fresh 15-minute preview ID plus confirm: true. After saving, the server reads the class back and compares names and counts.

Related MCP server: excel-mcp-server

What it can do

The workbook inspector does not assume fixed sheet names or column positions. It scans the whole workbook for common Chinese and English class/seat/name headers. Preview and verification then require an explicit non-empty sheetNames selection plus class mappings, preventing an Agent from silently combining duplicate or unrelated sheets.

Safe workflow

1. Run classdojo_doctor.

2. Run classdojo_inspect_workbook and select the intended sheet and detected class blocks.

3. Run classdojo_preview_roster_import with an explicit studentNameFormat.

4. Review class mappings, counts, missing seat numbers, and additions.

5. Only after human approval, call classdojo_apply_roster_import with the returned previewId and confirm: true.

6. Run classdojo_verify_roster_against_workbook for an independent read-back check.

All screenshots contain synthetic data only.

Requirements

• Node.js 20 or newer

• Chrome or another Chromium browser with Chrome DevTools Protocol (CDP)

• A ClassDojo teacher account that you sign in to yourself

• An MCP client that supports local stdio servers

The MCP server never asks for a ClassDojo password, cookie, or API token.

Start the local browser adapter

Use a dedicated browser profile and sign in to ClassDojo in that window.

macOS

open -na "Google Chrome" --args \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.classdojo-mcp-chrome"

Linux

google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.classdojo-mcp-chrome"

Windows PowerShell

& "$env:ProgramFiles\\Google\\Chrome\\Application\\chrome.exe" \`
  --remote-debugging-port=9222 \`
  --user-data-dir="$env:LOCALAPPDATA\\classdojo-mcp-chrome"

Keep the debugging port on loopback. Anyone who can reach a CDP endpoint may be able to control its browser session.

Install in an MCP client

Install from the public npm package with the same command in every client:

npx -y classdojo-mcp

Contributors can alternatively clone this repository, run npm ci && npm run build, and replace the command with node plus the absolute path to dist/cli.js.

Claude Desktop and Cursor

{
  "mcpServers": {
    "classdojo": {
      "command": "npx",
      "args": ["-y", "classdojo-mcp"],
      "env": {
        "CLASSDOJO_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

VS Code

{
  "servers": {
    "classdojo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "classdojo-mcp"],
      "env": {
        "CLASSDOJO_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.classdojo]
command = "npx"
args = ["-y", "classdojo-mcp"]

[mcp_servers.classdojo.env]
CLASSDOJO_CDP_URL = "http://127.0.0.1:9222"

Client UI and configuration locations change over time; refer to the client's current documentation. The transport itself is standard MCP stdio and is not Codex-specific.

Example tool inputs

Inspect a workbook first:

{
  "workbookPath": "/absolute/path/to/students.xlsx"
}

Create a preview with synthetic class mappings:

{
  "workbookPath": "/absolute/path/to/students.xlsx",
  "sheetNames": ["Grade 5"],
  "studentNameFormat": "seat_number_dot_name",
  "includeStudentDetails": false,
  "mappings": [
    {
      "classdojoClassName": "503",
      "sourceClassName": "Grade 5 Class 3"
    }
  ]
}

Apply only after reviewing the preview:

{
  "previewId": "00000000-0000-4000-8000-000000000000",
  "confirm": true
}

Preview IDs expire after 15 minutes, live only in the running MCP process, and are consumed by the first apply attempt. This reduces accidental replay and duplicate imports. If one class fails, the result names the verified classes and the classes that can be retried after generating a new preview.

Privacy and security

• Workbook parsing and browser automation run locally on the teacher's computer.

• The project does not run a hosted MCP service and does not persist credentials or student rosters.

• Student names may still pass through the selected MCP client/AI provider. Review that provider's retention and privacy terms before using real student data.

• Never attach real workbooks, student screenshots, browser profiles, cookies, or diagnostic logs containing personal data to a public issue.

• Only roster import is writable in v0.1.0. Points, attendance, messaging, family invitations, and other ClassDojo features are intentionally unavailable.

See docs/PRIVACY.md, SECURITY.md, and the threat model.

Troubleshooting

Project status and roadmap

Version 0.1.x is experimental. The web UI adapter is intentionally isolated so a future official ClassDojo API can replace it without changing the public MCP tool workflow.

Planned work:

• additional synthetic workbook layouts and locale coverage

• MCP client compatibility matrix and Inspector smoke tests

• official API adapter if ClassDojo grants Early Access

• optional read-only tools only after a privacy and permissions review

This project will not reverse-engineer or promise undocumented ClassDojo REST endpoints as a stable public API.

Development

npm ci
npm test
npm run build
npm audit --omit=dev
npm pack --dry-run

The stdio protocol uses stdout; never add console.log calls to the server. Use stderr for diagnostics. See CONTRIBUTING.md before opening a pull request.

Community metadata and release

• MCP Registry name: io.github.Eason0in/classdojo-mcp

• npm package: classdojo-mcp

• transport: stdio

• license: MIT

server.json and package.json#mcpName intentionally match the MCP Registry ownership format. The release workflow is prepared for a protected GitHub Actions environment, npm Trusted Publishing, provenance, and MCP Registry OIDC; it is not usable until the maintainer explicitly configures the release environment and npm publisher. No long-lived npm token belongs in this repository.

License

MIT © Eason0in