@vikranth2005/vtop-mcp

MCP server for VIT Chennai's VTOP student portal — read attendance, marks, timetable, exam schedule, grades, and curriculum progress from any MCP client (Claude Desktop, Claude Code, Cursor, …).

⚠️ Tested on VIT Chennai (vtopcc.vit.ac.in) only. Other VIT campuses (Vellore, AP, Bhopal) use different VTOP deployments whose HTML/endpoints may differ — they are unverified and the parsers may not work there. Pointing VTOP_BASE_URL at another campus is experimental and unsupported until tested. Reports/PRs from other campuses welcome.

Built by reverse-engineering the android-vtop-chennai app's communication with VTOP. Talks to the live portal with cookies + CSRF + authorizedID, exactly like a browser would.

Quick start (Claude Desktop)

Add this block to claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json; macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "vtop": {
      "command": "npx",
      "args": ["-y", "@vikranth2005/vtop-mcp"],
      "env": {
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}

That's the minimal config. VTOP_USERNAME and VTOP_PASSWORD are optional. Two ways to use it:

• Don't set them (above): the first time you ask something VTOP-related, the assistant will ask you for your VTOP username and password in the chat, then log in. Nothing is stored on disk.
• Set them (below): fully hands-free — you're never asked, the assistant logs in silently with the stored values.

{
  "mcpServers": {
    "vtop": {
      "command": "npx",
      "args": ["-y", "@vikranth2005/vtop-mcp"],
      "env": {
        "NODE_OPTIONS": "--use-system-ca",
        "VTOP_USERNAME": "your-vtop-username",
        "VTOP_PASSWORD": "your-vtop-password"
      }
    }
  }
}

Fully quit Claude Desktop (tray → Quit) and reopen. Then in a new chat, just say:

"What's my attendance?"

The assistant fetches a captcha, OCRs it, logs in (asking for credentials only if they aren't in the config), picks the current semester, and answers.

Other clients

Claude Code:

claude mcp add vtop -- npx -y @vikranth2005/vtop-mcp

Cursor / Windsurf / Cline / Zed — same JSON shape as Claude Desktop, dropped into the client's MCP config file.

Available tools (12)

| Tool | Args | Returns | |---|---|---| | get_captcha | — | Captcha image (the model OCRs it) | | login | captcha, username?, password? | Login result. User/pass optional when env vars are set. | | logout | — | Clears the session | | get_semesters | — | [{id, name}] of all available semesters | | get_profile | — | Name, regNo, program, branch, school, email, phone, blood group | | get_attendance | semesterId? | Per-course attended/total/percentage | | get_timetable | semesterId? | Courses, slots, venues, faculty, credits | | get_marks | semesterId? | Internal assessment components + weightages | | get_exam_schedule | semesterId? | CAT-1 / CAT-2 / FAT dates, venues, seat numbers | | get_semester_grades | semesterId? | Course-wise grades + GPA | | get_grade_history | — | CGPA, total credits, per-semester GPA + courses | | get_curriculum_progress | — | Credits earned vs required, per-category, per-basket, grade-letter counts |

All per-semester tools auto-pick the current semester if semesterId is omitted. The server probes the timetable for the 3 most recent semesters to find one with real course data (skips Summer Term when you're not enrolled).

Environment variables

| Variable | Required | Default | Purpose | |---|---|---|---| | VTOP_USERNAME | Optional | — | Auto-login username. If unset, the assistant asks you for it in the chat the first time you request VTOP data. | | VTOP_PASSWORD | Optional | — | Auto-login password. If unset, the assistant asks you for it in the chat. Never stored on disk when entered this way. | | NODE_OPTIONS | Recommended on Windows | — | Set to --use-system-ca so Node trusts VIT's TLS chain via the OS store. Without this you'll see unable to verify the first certificate. | | VTOP_BASE_URL | Optional | https://vtopcc.vit.ac.in/vtop | Override for other VIT campuses (see below). |

Campuses

| Campus | VTOP_BASE_URL | Status | |---|---|---| | VIT Chennai (default) | https://vtopcc.vit.ac.in/vtop | ✅ Tested & working | | VIT Vellore | https://vtop.vit.ac.in/vtop | ⚠️ Untested | | VIT-AP | https://vtop.vitap.ac.in/vtop | ⚠️ Untested | | VIT Bhopal | https://vtop.vitbhopal.ac.in/vtop | ⚠️ Untested |

Only VIT Chennai has been verified end-to-end. The other base URLs are provided for experimentation but the HTML parsers were written against VIT Chennai's VTOP and are likely to need adjustment for other campuses.

Security

Credentials in the env block of claude_desktop_config.json are stored in plaintext on disk, in your user's %APPDATA%. Only your OS user can read them. They are passed to the spawned node child process at startup and never traverse the network except to VTOP itself — they do not go to Anthropic, npm, or anywhere else.

The MCP server is a local stdio process; there's no listening port, no remote endpoint. Session cookies live in memory only and are cleared when Claude Desktop restarts.

Troubleshooting

'vtop-mcp' is not recognized / npx fails on Windows — some Windows npm setups don't resolve npx-of-a-scoped-package cleanly. Most reliable fix: install it globally and point the config at the command directly:

npm i -g @vikranth2005/vtop-mcp

{
  "mcpServers": {
    "vtop": {
      "command": "vtop-mcp",
      "env": { "NODE_OPTIONS": "--use-system-ca" }
    }
  }
}

(npm i -g installs a vtop-mcp command shim on your PATH; Claude Desktop runs it directly, no npx involved.) macOS/Linux/WSL users can use the npx -y @vikranth2005/vtop-mcp form from Quick start without issue.

unable to verify the first certificate — set NODE_OPTIONS: "--use-system-ca" in the env block. Node ≥ 22 needs the explicit flag to trust the OS CA store on Windows.

"It seems there are no attendance records" — almost always a stale spawned MCP process. Quit Claude Desktop fully (tray → Quit, not just the X), then reopen.

Login keeps failing — likely captcha misread. The model fetches a fresh one and retries automatically (up to 3 tries). After that, check the credentials in your env block.

Empty results when classes are running — VTOP HTML occasionally changes. Open an issue with a sanitized HTML snippet from the affected endpoint.

Development

git clone https://github.com/Vikranth-jagdish/VtopMCP
cd VtopMCP
npm install
npm run build
npm run test:mcp          # spawns dist/index.js, checks the wire protocol
npm run test:e2e          # interactive: solves a captcha and exercises every tool

Local claude_desktop_config.json for dev: point command at node and args at the absolute path to your dist/index.js instead of npx.

Project layout

src/
├── index.ts              stdio transport entry
├── server.ts             registers all 12 tools
├── services/
│   ├── vtop-client.ts    HTTP client, cookie jar, login flow, semester probe
│   ├── vtop-parser.ts    cheerio HTML → JSON parsers
│   └── constants.ts      endpoints, error strings, grade letters
├── tools/                one file per tool group
└── schemas/index.ts      Zod input schemas

How it works (high level)

1. Login is a 3-step dance. /vtop/login is a portal selector page (Student/Employee/Parent/Alumni) with no captcha. POSTing to /prelogin/setup?flag=VTOP (after grabbing the CSRF token) returns the actual student login page, which embeds a base64 captcha. We POST credentials + captcha back to /login; a hidden <input id="authorizedIDX"> in the response is the session token used for every subsequent request.
2. All data tools POST to endpoints like processViewStudentAttendance with authorizedID, _csrf, and semesterSubId. Responses are HTML; cheerio extracts the relevant tables.
3. Auto-semester selection probes the timetable for the three most recent terms and picks the first with real course rows — so it handles students not enrolled in Summer Term.

License

MIT — see LICENSE.

The HTML parsing logic is adapted from the android-vtop-chennai source under its respective license. This project is not affiliated with VIT.