VTOP Bhopal MCP

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.

Contents

• What it can do

• Quick start

• Connect it to your assistant

• How login works

• Privacy and security

• What's different from the Chennai version

• Troubleshooting

• Development

• Limitations

• Credits and license

Related MCP server: FAST-NUCES Flex Student Portal MCP Server

What it can do

Every per-semester tool picks the current semester automatically, so you rarely need to name one.

Quick start

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 build

Save your VTOP login (optional, recommended)

Create a file called .env in the project folder:

VTOP_USERNAME=your-registration-number
VTOP_PASSWORD=your-vtop-password

Then 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.

Connect it to your assistant

Replace /path/to/vtop-bhopal-mcp with where you cloned it (run pwd inside the folder to see it).

Claude Code

claude mcp add vtop-bhopal -s user -- node --env-file=/path/to/vtop-bhopal-mcp/.env /path/to/vtop-bhopal-mcp/dist/index.js

Check it's connected:

claude mcp list
# vtop-bhopal: ... - ✔ Connected

Start a new session and ask "what's my attendance?".

Claude Desktop

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.

Cursor, Windsurf, Cline, Zed and others

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.

How login works

1. The assistant calls get_captcha. VTOP shows a small text captcha, which the assistant reads from the image.

2. It calls login with that captcha (plus your saved username and password).

3. 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.

Privacy and security

• 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.

What's different from the Chennai version

VIT Bhopal's VTOP runs on the same platform as Chennai's but differs in the details. This fork changes:

The Bhopal-specific layouts are covered by offline test fixtures (synthetic data only) in scripts/fixtures.ts.

Troubleshooting

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.

Development

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 client

Live 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:

The upstream HTTP / ChatGPT-connector mode (dist/http.js) is still included but hasn't been tested on Bhopal.

Limitations

• 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.

Credits and license

• 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.