Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@VTOP Bhopal MCP Can I skip tomorrow's Analog class and still stay above 75%?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ask your AI assistant about your VIT Bhopal VTOP account: attendance, marks, timetable, exams, grades, the academic calendar, and "how many classes can I still skip?".
This is an MCP server. Once it's connected to Claude Code, Claude Desktop, Cursor or any other MCP client, you can just ask:
"What's my attendance?" "Which classes do I have on Monday?" "Can I skip any more Analog classes before the last instructional day?" "When is my Chemistry FAT, and where?" "What GPA do I need next semester to reach an 8 CGPA?"
The assistant logs in to VTOP for you (it reads the captcha itself), fetches the page, and answers in plain language.
It's a fork of VtopMCP, which was built for VIT Chennai. VIT Bhopal's VTOP looks similar but differs in many places, so this fork reworks the endpoints and parsers for Bhopal and has been tested against the live Bhopal portal.
Related MCP server: FAST-NUCES Flex Student Portal MCP Server
Tool | What you get |
| Attended / total / percentage per course |
| Bunk calculator: how many classes you can still skip (or must attend) to stay above 75%. Give it a date and it projects real classes up to that day using your timetable and the academic calendar. |
| Classes for today or any date, with times and rooms. Knows about holidays and Saturdays that follow another weekday's timetable. |
| Registered courses with slots, venues, faculty and credits |
| CAT and other internal-assessment marks with weightage |
| CAT-1, CAT-2 and FAT dates, sessions, times, venues and seats |
| Grades and GPA for one semester |
| CGPA, credits, and every course grouped by exam month |
| Credits earned vs required, by category and basket |
| Current CGPA, GPA for a set of grades, projected CGPA, GPA needed for a target |
| On-Duty days used this semester vs the event-OD limit (see note) |
| Academic calendar: holidays, exams, events, instructional days |
| Name, registration number, programme and branch, school |
| All your semesters and their IDs |
| Used by the assistant to sign in and out |
Every per-semester tool picks the current semester automatically, so you rarely need to name one.
You need Node.js 20.6 or newer (node -v to check) and git.
git clone https://github.com/divyarthjain/vtop-bhopal-mcp.git
cd vtop-bhopal-mcp
npm install
npm run buildCreate a file called .env in the project folder:
VTOP_USERNAME=your-registration-number
VTOP_PASSWORD=your-vtop-passwordThen make it readable only by you:
chmod 600 .env.env is in .gitignore, so it never gets committed. If you skip this step, the assistant asks for your username and password in the chat the first time it needs them.
Replace /path/to/vtop-bhopal-mcp with where you cloned it (run pwd inside the folder to see it).
claude mcp add vtop-bhopal -s user -- node --env-file=/path/to/vtop-bhopal-mcp/.env /path/to/vtop-bhopal-mcp/dist/index.jsCheck it's connected:
claude mcp list
# vtop-bhopal: ... - ✔ ConnectedStart a new session and ask "what's my attendance?".
Open Settings → Developer → Edit Config and add:
{
"mcpServers": {
"vtop-bhopal": {
"command": "node",
"args": [
"--env-file=/path/to/vtop-bhopal-mcp/.env",
"/path/to/vtop-bhopal-mcp/dist/index.js"
]
}
}
}Fully quit and reopen Claude Desktop.
Use the same command and args as the Claude Desktop example in your client's MCP config file.
Didn't create a
.env? Drop the--env-file=…argument. The assistant will ask for your login in the chat instead.
The assistant calls get_captcha. VTOP shows a small text captcha, which the assistant reads from the image.
It calls login with that captcha (plus your saved username and password).
It fetches what you asked for.
Things to know:
Sessions last about an hour. VTOP signs every session out roughly 60 minutes after login, however active you are. When that happens the assistant simply logs in again, and you may see it read a new captcha.
Sometimes VTOP shows a Google reCAPTCHA instead of the text captcha. The server reloads the login page a few times until the text captcha appears, so this is usually invisible to you.
A misread captcha isn't a problem. The assistant fetches a new one and tries again.
Your login only goes to VTOP. The server runs on your own computer and talks directly to vtop.vitbhopal.ac.in. It never sends your username or password anywhere else.
Nothing is stored except what you choose. Session cookies live in memory and vanish when the server stops. Your password is stored only in your own .env file, if you create one.
Your assistant sees your data. Whatever the tools return (marks, attendance and so on) goes to the AI assistant you connected, the same as anything else you ask it about.
The test scripts save raw VTOP pages to test-output/. Those pages contain your personal data, which is why that folder is git-ignored. Don't share it.
.env is plain text. Keep it chmod 600 and don't commit it.
VIT Bhopal's VTOP runs on the same platform as Chennai's but differs in the details. This fork changes:
Area | Chennai (upstream) | Bhopal (this fork) |
Portal |
|
|
Semester list |
|
|
Attendance | separate code / title / slot columns | combined "Course Detail" and "Class Detail" cells; header row has no |
Per-class attendance (OD) |
|
|
Exam schedule | header row first | an extra "General (Semester)" row above the header |
Semester grades | single Credits column | Credits split into L / P / J / C, plus Grading Type and Grand Total |
Grade history | grouped by exam month | same, but course codes like |
Profile branch | "Branch" field | taken from the grade-history header (the profile page only has the Class 12 stream) |
Calendar | one entry per day | every student group listed per day; only the "General" entry is used. Saturdays marked "Activities Friday" follow Friday's timetable. |
OD limit | 40 hours per semester | event-OD days (see note) |
The Bhopal-specific layouts are covered by offline test fixtures (synthetic data only) in scripts/fixtures.ts.
The assistant doesn't see the VTOP tools. Start a new session after adding the server; tools load at startup. In Claude Code, claude mcp list should show ✔ Connected.
node: bad option: --env-file. Your Node is older than 20.6. Update Node, or drop the --env-file argument and log in through the chat.
"Invalid username or password". Check .env for typos and stray spaces around =. Try logging in on the VTOP website to be sure.
Login keeps failing on the captcha. It's usually a misread; the assistant retries. If VTOP keeps serving the Google reCAPTCHA, wait a few minutes and try again.
timeout of 30000ms exceeded. VTOP is slow (common late at night or on result days). Add VTOP_TIMEOUT_MS=60000 to your .env.
A tool returns empty data while you can see it on the website. VTOP's pages change from time to time. Please open an issue with the tool name and what you expected. Don't paste raw pages or screenshots that show personal details.
npm install
npm run build # compile to dist/
npm run test:parser # offline parser checks (Chennai + Bhopal fixtures)
npm run test:tools # offline tool checks with a fake VTOP clientLive checks against the real portal (needs your login in .env; you type the captcha):
npm run test:e2e # core tools, parser level
VTOP_MCP_TOOLS=1 npm run test:e2e # every tool through the real MCP server
VTOP_MENU_DUMP=1 npm run test:e2e # list VTOP's menu pages and save them
VTOP_DUMP_HTML=1 npm run test:e2e # also save raw HTML to test-output/Useful environment variables:
Variable | Default | Purpose |
| none | Auto-login. Without them the assistant asks in chat. |
|
| Portal address |
|
| Per-request timeout |
The upstream HTTP / ChatGPT-connector mode (dist/http.js) is still included but hasn't been tested on Bhopal.
Unofficial. Not affiliated with or endorsed by VIT Bhopal. It reads the same pages your browser does; if VTOP changes them, parts may break until updated.
Read-only. It only signs in and reads pages. It never registers courses or changes anything on VTOP, and fee and payment pages are never opened.
OD limit is unconfirmed. calculate_od counts distinct OD days against 8, based on students' understanding that about 8–9 event ODs are allowed and DSW-approved ODs are unlimited. VTOP doesn't mark which ODs were DSW-approved, so all OD days are counted. Check the official rule with your school or the DSW office, and if you have a source, please open an issue.
Bunk calculator uses 75%, treating 74.x% as safe, as upstream does. Check your own course rules.
Tested on a B.Tech account (Fall Semester 2026-27). Other programmes may see different layouts.
Original project: VtopMCP by Vikranth Jagdish (MIT License), itself based on how the android-vtop-chennai app talks to VTOP.
This fork is released under the Apache License 2.0. Code from the original project remains under its MIT terms; see NOTICE and LICENSE-MIT-upstream.
Attendance / bunk calculator. Per course: current %, whether you're safe (strictly above 74.0% by default — 74.0 is debarred; override via targetPercent), how many more classes you can skip ('bunkBuffer'), and how many to attend to recover ('classesToRecover'). For the key real use case — 'I'm at the line; if I skip today can I still make 75% by the time attendance closes?' — pass untilDate (the attendance-closing date; ASK THE USER for it) and bunkDates (the days you'd skip, e.g. today's date). Using the timetable + academic calendar (holidays, working Saturdays / day-orders) it returns per course: upcomingSessions until the deadline, ifAttendAllPercent/ifSkipAllPercent, maxSkippableInRange, mustAttendInRange, canBeSafeByDeadline, and — when bunkDates is given — plannedBunk (your final % and whether you're still safe if you skip exactly those days and attend everything else). Also returns a perDay breakdown of which classes fall on each upcoming day. If the response contains NOT_AUTHENTICATED, call get_captcha then login then retry. login auto-uses VTOP_USERNAME/VTOP_PASSWORD env vars if set; if it reports credentials missing, ask the user for them. Requires login.
Inputs: bunkDates, untilDate, courseCode, semesterId, +2 more.
GPA / CGPA / percentage calculator on VIT's 10-point scale (S=10 A=9 B=8 C=7 D=6 E=5 F=0; percentage = CGPA×10). It works from the LETTER GRADES VTOP already awarded — whether those were decided by relative or absolute grading doesn't matter, the grade→point scale is the same for every course. With no arguments it reports your current CGPA, percentage, total credits, and each completed semester's GPA. Pass courses (credits + grade for each) to compute that set's GPA and your projected CGPA — for 'what-if' scenarios where you supply expected grades (the most reliable way to forecast). Pass targetCgpa (+ plannedCredits) for the GPA needed to reach that CGPA. Pass semesterId (no courses) to compute one stored semester's GPA. (To estimate grades from current MARKS, use predict_grades instead.) If the response contains NOT_AUTHENTICATED, call get_captcha then login then retry. Requires login.
Inputs: courses, semesterId, targetCgpa, currentCgpa, +2 more.
Count your On-Duty (OD) days this semester from the per-class attendance detail and check them against VIT Bhopal's event-OD limit (~8; DSW-approved ODs don't count but VTOP can't tell them apart, so all are counted). Returns distinct OD days with dates, OD classes per course, days remaining, and whether you're over. Always pass on the returned "note" about the rule being unconfirmed. This reads each course's attendance detail, so it makes several requests. If the response contains NOT_AUTHENTICATED, call get_captcha then login then retry. Requires login.
Inputs: courseCode, semesterId.
Get attendance records for all courses (attended/total/percentage per course). If the response contains NOT_AUTHENTICATED, immediately call get_captcha then login then retry this tool. login auto-uses VTOP_USERNAME/VTOP_PASSWORD env vars if set; if login replies that credentials are missing, ask the user for their VTOP username and password and call login again with them. semesterId is optional; omit for current semester. Requires login.
Inputs: semesterId.
Look up the academic calendar: holidays, events (e.g. TechnoVIT), working Saturdays / day-orders, and which days are instructional. Use query to find a named event/holiday (e.g. 'technovit', 'pongal'), month ('YYYY-MM') to list a month, or holidaysOnly for just the no-class days; with no filter it returns the semester's notable days (holidays + working-Saturday day-orders). Festivals/holidays belong to the term they fall in, so if a query finds nothing, call get_semesters and retry with that semester's id. If the response contains NOT_AUTHENTICATED, call get_captcha then login then retry. Requires login.
Inputs: month, query, semesterId, holidaysOnly.
Step 1 of login: fetch a CAPTCHA image from VTOP. Returns the image so you (the model) can OCR it. After this, immediately call login with the captcha text you read — do NOT ask the user to read it for you. The user only needs to be asked for credentials if VTOP_USERNAME / VTOP_PASSWORD are not set as env vars on the server.
Inputs: no named parameters.
Get degree progress: total credits earned vs required (and remaining), per-category breakdown (Foundation Core, Discipline Core, Discipline Electives, Open Electives, Projects/Internship, etc.), per-basket completion (HSM Elective, Foreign Language, Extra-curricular, ...), CGPA, and grade-letter counts across all semesters. Use this for any 'how many credits left?', 'how close am I to graduating?', 'which baskets do I still need?', or 'how many of each grade have I gotten?' questions. If the response contains NOT_AUTHENTICATED, immediately call get_captcha then login then retry this tool. login auto-uses VTOP_USERNAME/VTOP_PASSWORD env vars if set; if login replies that credentials are missing, ask the user for their VTOP username and password and call login again with them. Requires login.
Inputs: no named parameters.
Get exam schedule (CAT1/CAT2/FAT dates, timings, venues, seat numbers, row/col). If the response contains NOT_AUTHENTICATED, immediately call get_captcha then login then retry this tool. login auto-uses VTOP_USERNAME/VTOP_PASSWORD env vars if set; if login replies that credentials are missing, ask the user for their VTOP username and password and call login again with them. semesterId is optional; omit for current semester. Requires login.
Inputs: semesterId.
Get cumulative grade history (CGPA, total earned credits, per-semester GPA + courses + grades, grouped by exam month). If the response contains NOT_AUTHENTICATED, immediately call get_captcha then login then retry this tool. login auto-uses VTOP_USERNAME/VTOP_PASSWORD env vars if set; if login replies that credentials are missing, ask the user for their VTOP username and password and call login again with them. Requires login.
Inputs: no named parameters.
Get internal marks/assessment scores (component-wise marks, weightage, status). If the response contains NOT_AUTHENTICATED, immediately call get_captcha then login then retry this tool. login auto-uses VTOP_USERNAME/VTOP_PASSWORD env vars if set; if login replies that credentials are missing, ask the user for their VTOP username and password and call login again with them. semesterId is optional; omit for current semester. Requires login.
Inputs: semesterId.
Get student profile (name, registration number, application number, program, branch, school, email, phone, blood group). If the response contains NOT_AUTHENTICATED, immediately call get_captcha then login then retry this tool. login auto-uses VTOP_USERNAME/VTOP_PASSWORD env vars if set; if login replies that credentials are missing, ask the user for their VTOP username and password and call login again with them. Requires login.
Inputs: no named parameters.
Get grades for a specific semester (course-wise grades + GPA). If the response contains NOT_AUTHENTICATED, immediately call get_captcha then login then retry this tool. login auto-uses VTOP_USERNAME/VTOP_PASSWORD env vars if set; if login replies that credentials are missing, ask the user for their VTOP username and password and call login again with them. semesterId is optional; omit for current semester. Requires login.
Inputs: semesterId.
Get list of available semesters (id + name). Most data tools accept the semesterId, but they also default to the current semester if omitted — so you usually don't need to call this unless the user asks about a specific past semester. If the response contains NOT_AUTHENTICATED, immediately call get_captcha then login then retry this tool. login auto-uses VTOP_USERNAME/VTOP_PASSWORD env vars if set; if login replies that credentials are missing, ask the user for their VTOP username and password and call login again with them. Requires login.
Inputs: no named parameters.
Get class timetable/schedule (courses, slots, venues, faculty, credits). If the response contains NOT_AUTHENTICATED, immediately call get_captcha then login then retry this tool. login auto-uses VTOP_USERNAME/VTOP_PASSWORD env vars if set; if login replies that credentials are missing, ask the user for their VTOP username and password and call login again with them. semesterId is optional; omit for current semester. Requires login.
Inputs: semesterId.
List the classes scheduled for today (or a given date) with their time and venue, accounting for the academic calendar — returns a holiday/no-class result on non-instructional days, and follows the correct day-order on working Saturdays (e.g. a Saturday running the Thursday timetable). Pass date (ISO YYYY-MM-DD) to check another day. If the response contains NOT_AUTHENTICATED, call get_captcha then login then retry. Requires login.
Inputs: date.
Step 2 of login: submit credentials + the captcha you just OCR'd. Username/password are optional — if VTOP_USERNAME and VTOP_PASSWORD are set as env vars on the MCP server, omit them and the server uses the stored values. Only ask the user for credentials if the server reports they're not configured.
Inputs: captcha (required), password, username.
Logout from VTOP and clear the session.
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 17 tools
Most tools have clearly distinct purposes (attendance, timetable, marks, exam schedule, profile, calendar). There is mild overlap among the grade-related tools (get_grade_history, get_semester_grades, get_curriculum_progress, calculate_gpa) and attendance tools (get_attendance vs calculate_attendance), but descriptions differentiate raw data vs. computed/aggregated views adequately.
Dominant pattern is verb_noun with get_* (get_attendance, get_timetable, get_marks, get_profile, etc.) and calculate_* (calculate_gpa, calculate_attendance, calculate_od), which is predictable. The auth tools login/logout/get_captcha deviate slightly by being bare verbs, but overall it is coherent.
17 tools is on the heavier side but each maps to a distinct academic concern (auth flow, grades, attendance, timetable, calendar, calculators, profile). Nothing feels redundant enough to trim, though it approaches the upper bound for a single-portal server.
The surface covers the core student lifecycle well: authentication, profile, attendance, marks, grades, exam schedule, timetable, academic calendar, and GPA/attendance calculators. Missing operations like course registration or fee/hostel details are outside the apparent scope, so coverage is strong with only minor gaps.
Connect AI assistants to Edusign attendance, courses, learners, documents, and API docs via OAuth.
Logs your AI agent into websites, catches verification codes, and asks you before anything risky.
Your life dashboard for AI: tasks, habits, goals, budgets, workouts, nutrition, journal, notes.
Let your AI agent operate any website through a real, logged-in browser session.