MyCourseVille MCP Server

An MCP server that gives an AI agent access to your MyCourseVille account: new assignments with their deadlines and descriptions, course materials, and released grades — plus a "what changed since last time" feed.

Personal tool for your own account data. Keep the poll interval polite and never commit your credentials.

How it works

MCV has an official OAuth2 API (/api/v1/public/get/*), but it requires registering an app to get a client_id/client_secret, and its endpoint names aren't publicly documented. This server instead logs in exactly like the MCV web client does — through the IT Chula SSO button by default, or the plain MCV form — then reads the same server-rendered course pages the site serves to a browser: the course home for materials, /assignment for deadlines, and /portfolio-<student id> for scores. See docs/ENDPOINTS.md.

Fetched data lands in a local SQLite snapshot. Every sync diffs against that snapshot and appends to an events log — that log is what whats_new reads, so the server can tell you what appeared since you last looked. A background poller refreshes on an interval so a new assignment is noticed even when no chat is open.

On "new": MCV doesn't reliably expose a posted-at timestamp, so first_seen — when this server first observed an item — is the proxy. The first sync backfills everything quietly rather than reporting your entire semester as new.

Setup

uv sync --extra dev
cp .env.example .env      # then fill in MCV_USERNAME / MCV_PASSWORD
uv run mcv-mcp --selftest

--selftest logs in, syncs once, and prints how many courses, assignments, materials and grades it found. Get that working before wiring up the agent.

Register with Claude Code:

claude mcp add mcv -- uv --directory C:\Users\velys\Documents\mcp_mcv run mcv-mcp

Then ask: "What's due this week?", "Anything new on MCV since yesterday?", "Download the latest slides for Comp Prog."

Tools

Tool	What it answers
whats_new	New/changed assignments, materials and grades since a point in time
list_upcoming_deadlines	What's due in the next N days, soonest first
list_courses	Enrolled courses, optionally one semester
list_assignments	Assignments with deadline + description
get_assignment	Full detail for one assignment
list_materials	Files posted in a course (folder, name, URL)
download_material	Save a file locally; extracts PDF text so it can be read
list_grades	Released scores
sync_now	Force a refresh (full=true for all semesters)
auth_status	Diagnostics: login state, last sync, row counts

Configuration

Variable	Default	Meaning
MCV_USERNAME / MCV_PASSWORD	—	Your MCV credentials
MCV_LOGIN_METHOD	itchula	itchula for the IT Chula SSO button, mcv for the plain form
MCV_POLL_MINUTES	30	Poller interval (floor 10)
MCV_POLL_ENABLED	1	Set 0 to disable background polling
MCV_STATE_DIR	%LOCALAPPDATA%\mcv_mcp	Where the DB, cookies and downloads live

State is kept outside the repo. Cookies are persisted, so restarts don't re-login.

Run the poller separately (e.g. under Task Scheduler) with:

uv run python -m mcv_mcp.poller

Layout

src/mcv_mcp/
  config.py    settings, URLs, state paths
  client.py    Chula SSO login, cookie persistence, throttled AJAX transport
  parsers.py   HTML -> dicts (pure functions, fixture-tested)
  store.py     SQLite snapshot + event log
  sync.py      orchestration + background poller
  server.py    MCP tool definitions

MCV's markup is the fragile part, and it's confined to parsers.py. If something stops returning rows, capture a fresh fixture (see docs/ENDPOINTS.md) and fix the selector there.

Status

Working against a real account: login, all four parsers, downloads and change detection are verified end to end. A representative sync pulled 9 courses, 20 assignments (every one with a parsed deadline), 112 materials and 69 graded items; the following sync reported zero changes, so the diff log stays quiet until something actually moves.

Known limits:

• Grade release is detected by polling, not pushed. A score appearing shows up as a grade_changed event within one poll interval (default 30 min).
• Only the current semester is synced unless you pass full=true to sync_now.
• MCV's markup is the fragile part. If a parser starts returning zero rows, capture a fixture and fix the selector — see docs/ENDPOINTS.md.

Development

uv run pytest