iitkgp-erp-mcp

MCP server for IIT Kharagpur ERP. Query your grades, CGPA, attendance, timetable, placements, and more through any AI agent.

Works with: Claude Code, Claude Desktop, Cursor, Cline, Continue, Zed, custom agents — anything that speaks MCP.

Install

pip install iitkgp-erp-mcp
playwright install chromium

Setup

iitkgp-erp-setup

This stores your credentials securely in your OS keychain.

Usage

Add to your MCP client config (.mcp.json, mcp_servers.json, etc.):

{
  "mcpServers": {
    "iitkgp-erp": {
      "command": "iitkgp-erp-mcp"
    }
  }
}

Then ask your AI agent:

• "What's my CGPA?"
• "Show my grades for semester 4"
• "Compare my performance in CS vs MA subjects"
• "If I get A in all subjects this sem, what's my CGPA?"
• "Which breadth electives should I take?"
• "Any new placement notices for SDE roles?"
• "Can I skip tomorrow's Signals class?"
• "What's my schedule today?"
• "Export my timetable to Google Calendar"
• "Browse the fee payment page"

Available Tools (25)

Grades & GPA

Tool	Description
erp_login	Login to ERP (handles OTP)
erp_logout	End session
get_grades	Fetch grades (all or specific semester)
get_cgpa	Current CGPA
get_sgpa	SGPA for a semester
get_cgpa_trend	Semester-wise CGPA/SGPA progression
compare_subjects	Compare across subjects
what_if_cgpa	Projected CGPA calculator
get_grade_distribution	Grade breakdown (EX/A/B/C/D/P/F counts)

Attendance

Tool	Description
get_attendance	All subjects with attendance %
get_attendance_alerts	Subjects below 80% danger zone
can_i_skip	How many classes you can safely miss

Elective Recommender

Tool	Description
recommend_electives	Suggests electives based on your grade patterns
get_strengths_weaknesses	Your top 5 best/worst subjects
get_department_performance	Average GPA by department

Timetable & Schedule

Tool	Description
get_timetable	Full week or specific day schedule
get_today_classes	Today's classes
where_is_prof	Find a professor's location via timetable
export_timetable_ics	Export to ICS format (Google Calendar, Apple Calendar)

Placements & Notices

Tool	Description
get_placement_notices	CDC notices, filterable by keyword
get_notice_detail	Full text of a specific notice
get_academic_notices	Academic announcements

Explorer

Tool	Description
browse_erp_page	Navigate any ERP page freely
search_erp_pages	Find ERP pages by keyword

Utility

Tool	Description
clear_cache	Clear locally cached data

Security

• Credentials stored in OS keychain (never plaintext)
• Session is local to your machine
• OTP entered live, never stored
• Nothing sensitive is committed to git

How it works

Your AI Agent ←→ MCP Protocol (stdio) ←→ iitkgp-erp-mcp server
                                              │
                                              ├── iitkgp-erp-login (auth)
                                              ├── requests + BeautifulSoup (scraping)
                                              └── Playwright (JS-heavy pages)
                                              │
                                              ▼
                                        erp.iitkgp.ac.in

Grading Scale

Grade	Points
EX	10
A	9
B	8
C	7
D	6
P	5
F	0

Roadmap

• [x] Grades & GPA tools
• [x] Attendance tracking + alerts
• [x] Elective recommender
• [x] Placement notice integration
• [x] Timetable extraction
• [x] Calendar sync (ICS export)
• [x] Prof finder
• [x] Academic notices
• [x] Freeform ERP browser
• [ ] Batch grade distributions (historical data)
• [ ] Registration status
• [ ] Fee payment status
• [ ] Hostel info

Contributing

PRs welcome! The scrapers in src/scrapers/ may need selector updates if ERP changes its HTML structure.

License

MIT