camcors-mcp

An unofficial MCP server for Cambridge's CamCORS (Online Reporting of Supervisions) system.

The server uses a visible Chrome window for Raven sign-in and report previews. It sends report requests to the same internal endpoints as the CamCORS web pages. These endpoints are not a published API.

Raven credentials and CamCORS cookies stay in a dedicated Chrome profile. The server does not accept them as tool arguments, print them to logs or store them in this repository.

[!CAUTION] CamCORS contains confidential student and payment information. Use this server only with an account you are authorised to use. Do not add real report data to the repository. Check each write action in the Chrome window.

What it does

• Opens CamCORS in a persistent Chrome profile.
• Lists supervision and non-supervision reports.
• Reads a report by its CamCORS report ID.
• Prepares and creates supervision report drafts.
• Reads the editable fields from a Draft or Returned report.
• Edits report fields and supervision timings.
• Deletes Draft or Returned reports after a separate confirmation.
• Validates reports without submitting them.
• Submits reports after a separate confirmation.
• Discards an unused preview without changing CamCORS.

camcors_create_supervision_drafts creates drafts. It does not submit them. Submission uses separate validation and confirmation tools.

Requirements

• Node.js 22 or newer
• Google Chrome
• Access to https://apps.casc.cam.ac.uk/ors/

Install

npm ci
npm run build

Run the tests and type checks:

npm test
npm run typecheck

Configure an MCP client

Use the absolute path to dist/index.js. For example:

{
  "mcpServers": {
    "camcors": {
      "command": "node",
      "args": ["/absolute/path/to/camcors-mcp/dist/index.js"],
      "env": {
        "CAMCORS_USER_DATA_DIR": "/absolute/path/to/.camcors-mcp/chrome-profile"
      }
    }
  }
}

The default profile path is ~/.camcors-mcp/chrome-profile. You can omit the env block if you use that path.

Sign in for the first time

1. Call camcors_open.
2. Sign in with Raven in the Chrome window.
3. Call camcors_open again.
4. Check that the result contains "authenticated": true.

The dedicated profile keeps the login between server runs. The server does not copy cookies from your usual browser profile.

Use an existing remote-debugging Chrome session

Set this variable if Chrome is already running with remote debugging:

CAMCORS_CDP_URL=http://127.0.0.1:9222

Recent Chrome versions require a non-default --user-data-dir for remote debugging. On macOS, start a dedicated instance with:

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.camcors-mcp/chrome-profile"

Sign in to CamCORS in that window. Then start the server with CAMCORS_CDP_URL set.

Create, edit, delete and submit reports

Create report drafts

1. Call camcors_prepare_supervision_drafts. It fills in the CamCORS form and returns a preview token.
2. Check the students, term, Tripos part, paper and topic in CamCORS.
3. Call camcors_create_supervision_drafts with the token and confirm: true.

Edit a report and set supervision timings

1. Call camcors_get_editable_report with a Draft or Returned report ID.
2. Use the returned field names and option values in camcors_prepare_report_edit.
3. To replace the timings, pass the complete groups list. Set size to the number of students in the group. Set totalMinutes to the total time taught to groups of that size.
4. Check the CamCORS edit form.
5. Call camcors_save_report_edit with the token and confirm: true.

The server reads the editable fields from the live form. It does not use a fixed list. A control without a form name has a key such as #controlId. This applies to controls such as the visible payment option selector. CamCORS updates the corresponding hidden values when these controls change.

The server applies the same basic timing checks as the CamCORS form:

• Group sizes are positive and unique.
• Durations are whole minutes and at least 15 minutes.
• An empty list requires allowNoGroups: true. CamCORS might still return a warning.

Delete a Draft or Returned report

1. Call camcors_prepare_report_deletion with the report IDs.
2. Check the exact reports in the CamCORS preview.
3. Call camcors_delete_reports with the returned deletionToken and confirm: true.

The server checks that each report is still a Draft or Returned report. It checks the reports again immediately before deletion and verifies that they no longer appear afterwards. A deletion token is used once. If the request fails without a clear result, inspect CamCORS before trying again.

Validate and submit reports

1. Save all intended edits.
2. Call camcors_prepare_report_submission with one or more report IDs.
3. Fix each error and read each warning.
4. If validation passes, call camcors_submit_reports with the returned submissionToken and confirm: true.
5. If validation returned warnings, also set acknowledgeWarnings: true.

The server calls the CamCORS validation action directly. This avoids the web page's automatic submission behaviour when validation returns no warnings. The server validates the reports again before submission. The result must match the preview. It uses each submission token once and consumes it before the network request. If the request fails without a clear result, check CamCORS before trying again.

Preview tokens expire after 30 minutes. They are also lost when the MCP process exits.

How it connects to CamCORS

CamCORS has no published API for report submission. This server uses the internal HTTP requests made by CamCORS v7:

• report search and report detail requests
• draft creation and report save form posts
• report deletion, validation and final submission actions

The request client shares Chrome's cookie jar. It does not copy cookies into environment variables or MCP messages. Each request is restricted to the configured CamCORS origin and /ors/ path. Write requests include the anti-forgery token when the current CamCORS form provides one.

The server still opens CamCORS pages when it needs Raven sign-in, a preview or CamCORS form JavaScript. This includes student lookup and the timing controls on the report edit form.

Environment variables

Variable	Default	Purpose
CAMCORS_BASE_URL	https://apps.casc.cam.ac.uk/ors/	CamCORS application root
CAMCORS_USER_DATA_DIR	~/.camcors-mcp/chrome-profile	Dedicated persistent Chrome profile
CAMCORS_HEADLESS	false	Run Chrome without a visible window
CAMCORS_CDP_URL	unset	Attach to an existing remote-debugging Chrome
CAMCORS_ACTION_TIMEOUT_MS	30000	Browser action timeout

Security

• The server marks report text as untrusted data.
• It runs browser operations in sequence.
• It restricts report URLs to the configured CamCORS origin and /ors/ path.
• Edit tools accept only fields found in the current CamCORS form.
• Deletion requires an exact report preview and separate confirmation.
• Submission requires validation and confirmation. Warnings also require acknowledgement.
• Automated tests do not use the live site.
• Do not commit .env files, browser profiles, screenshots, downloaded reports, CRSids or fixtures based on real reports.

See SECURITY.md for reporting and operating guidance.

Known limits

The selectors and internal requests were checked against CamCORS v7 on 29 July 2026. CamCORS can change them without notice. Such a change might require an update to this server.

The full edit and submission flow covers supervision reports. Non-supervision reports and general claims currently have read support only.