minerva-mcp

English | 简体中文

An unofficial, read-only MCP server for the University of Leeds' Minerva (Blackboard Learn Ultra) and Gradescope. It follows the approach of campus-cli. You sign in yourself in a real browser window, and the server reuses that session. Minerva data comes from the Blackboard REST API. Gradescope data comes from its web pages, because Gradescope has no API for students.

Security

• You type your password and MFA code into an Edge or Chrome window yourself. The scripts never see them.

• Sessions are saved in ~/.minerva-mcp/session.json and ~/.minerva-mcp/gradescope-session.json. The browser profile is in ~/.minerva-mcp/browser-profile. None of these are inside the project folder.

• The clients send only GET requests, and only to minerva.leeds.ac.uk and www.gradescope.com. When a file download redirects to Blackboard's file host, the session cookie is dropped. Nothing is ever submitted on your behalf.

• There is no telemetry.

Related MCP server: mun-d2l-mcp

Usage

Run these commands inside this folder:

npm install
npm run login              # opens a browser; sign in to Minerva and the window closes itself
npm run login:gradescope   # sign in to Gradescope (School Credentials → University of Leeds, or open any Gradescope link from Minerva)
npm run check              # prints your name and current courses

A Blackboard session usually expires after a few hours. When it does, run npm run login again. If Gradescope expires, run npm run login:gradescope. The browser profile keeps Microsoft's "Stay signed in" state, so later logins usually don't ask for your password again.

Add to Claude Code

claude mcp add minerva --scope user -- node "<absolute path to this folder>/src/server.js"

Or add it as JSON config, either in Claude Desktop's claude_desktop_config.json or in a project's .mcp.json:

{
  "mcpServers": {
    "minerva": { "command": "node", "args": ["<absolute path>/src/server.js"] }
  }
}

Tools

Environment variables

• MINERVA_BROWSER: the browser channel used for login (msedge or chrome). Edge is tried first by default.

• MINERVA_MCP_HOME: the session folder. Defaults to ~/.minerva-mcp.

• MINERVA_DOWNLOAD_DIR: the download folder. Defaults to ~/Downloads/minerva.

Known limitations

• Tested with a student account on 2026-10-16. Courses, announcements, outlines, attachment downloads, gradebook, deadlines and calendar all work. The gradebook only has entries for graded items; items that haven't been graded yet show graded: false.

• Minerva only knows the due date of a Gradescope assignment. For its submission status and score, use the gradescope_* tools.

• In both the Minerva and Gradescope tools, courseId accepts a short module code such as COMP3620 and matches the most recent course with that code.

• The Gradescope support works by parsing web pages, so a Gradescope redesign may require updating the parser.

• Content inside third-party LTI tools such as Turnitin and Panopto is not available.

• Please use this responsibly and follow the University's IT policies.

Contributing

See CONTRIBUTING.md. main is protected: changes go through pull requests and must pass CI (npm test). To report a security issue, see SECURITY.md.

License

ISC