🎓 LMS MCP Server - PAF-IAST University Automation
A powerful Model Context Protocol (MCP) server that automates PAF-IAST LMS interactions with AI assistants like Claude, Cursor, and VS Code Copilot.
🌟 Features
🔐 Smart Authentication
- Automated login with advanced CAPTCHA solving
- Google Gemini Vision API integration for enhanced accuracy
- Secure session management with encryption
- Automatic session persistence and restoration
📊 Academic Data Access
- Attendance Tracking - Real-time attendance records by subject
- Marks & Grades - Comprehensive exam scores and assessments
- Timetable Management - Class schedules and academic calendar
- Application System - Submit and track university applications
🤖 AI-Powered Automation
- Headless browser operation for efficiency
- Intelligent form handling and DOM navigation
- Robust error handling and retry mechanisms
- Multi-method CAPTCHA solving (Vision AI + OCR)
🛡️ Security & Privacy
- Environment-based configuration
- Encrypted session storage
- No hardcoded credentials
- Secure API key management
🚀 Quick Start
📋 Prerequisites
- Python 3.11+
- Git
- Chrome Browser (for automation)
- Google Gemini API Key (optional, for enhanced CAPTCHA solving)
📦 Installation
-
Clone the repository:
git clone <your-repo-url> cd LMS-MCP -
Install dependencies:
# Using uv (recommended) uv sync # Or using pip pip install -e . -
Configure environment:
# Copy the example environment file cp .env.example .env # Edit with your credentials (see Configuration section) notepad .env # Windows nano .env # Linux/Mac
⚙️ Configuration
📝 Environment Setup
Edit your .env file with the following settings:
# Required: Your PAF-IAST credentials
LMS_USERNAME=your_student_id_here
LMS_PASSWORD=your_password_here
# Optional: Enhanced CAPTCHA solving
GEMINI_API_KEY=your_gemini_api_key_here
# Browser settings
BROWSER_HEADLESS=true # Set to false for debugging
# Session settings
SESSION_EXPIRY_HOURS=24
ENCRYPT_SESSIONS=true
🔑 Getting Google Gemini API Key (Optional but Recommended)
- Visit Google AI Studio
- Sign in with your Google account
- Click "Create API Key"
- Copy the API key to your
.envfile
🔧 Setup with AI Assistants
🤖 Claude Desktop Setup
-
Locate Claude configuration file:
# Windows %APPDATA%\Claude\claude_desktop_config.json # macOS ~/Library/Application Support/Claude/claude_desktop_config.json # Linux ~/.config/Claude/claude_desktop_config.json -
Add MCP server configuration:
{ "mcpServers": { "lms-automation": { "command": "python", "args": ["C:/path/to/your/LMS-MCP/main.py"], "env": { "PYTHONPATH": "C:/path/to/your/LMS-MCP" } } } } -
Restart Claude Desktop
-
Test the connection:
Can you check my LMS attendance?
💻 Cursor IDE Setup
-
Open Cursor IDE
-
Go to Settings (Ctrl/Cmd + ,)
-
Navigate to Extensions → MCP
-
Add new MCP server:
{ "name": "LMS Automation", "command": "python", "args": ["./main.py"], "cwd": "/path/to/LMS-MCP", "env": { "PYTHONPATH": "/path/to/LMS-MCP" } } -
Restart Cursor
-
Test in chat:
@lms-automation login to LMS and check my marks
🆚 VS Code with GitHub Copilot Setup
-
Install MCP Extension:
- Open VS Code
- Go to Extensions (Ctrl+Shift+X)
- Search for "MCP Client" and install
-
Configure MCP server:
Create
.vscode/settings.jsonin your project:{ "mcp.servers": [ { "name": "lms-automation", "command": "python", "args": ["main.py"], "cwd": "${workspaceFolder}", "env": { "PYTHONPATH": "${workspaceFolder}" } } ] } -
Use with Copilot Chat:
- Open Copilot Chat (Ctrl+Shift+I)
- Type:
@mcp:lms-automation login and get my attendance
🛠️ Available MCP Tools
🔐 Authentication
login_to_lms- Login with credentials and CAPTCHA solvinglogout_lms- Logout and clear session
📊 Academic Data
check_attendance- Get attendance records by subjectget_marks- Retrieve marks and gradesget_timetable- Access class schedule
📝 Applications
create_application- Submit university applicationsview_application_status- Check application status
🔧 Utilities
solve_captcha- Manual CAPTCHA solving
💡 Usage Examples
Basic Login and Data Retrieval
# Login to LMS
Login to PAF-IAST LMS with my credentials
# Check attendance
What's my current attendance status?
# Get marks
Show me my latest marks and grades
# View timetable
What's my class schedule for today?
Advanced Queries
# Comprehensive report
Generate a summary report of my academic performance including attendance, marks, and upcoming classes
# Specific subject
What's my attendance percentage for Computer Science subjects?
# Application tracking
Check the status of my scholarship application
🔍 Troubleshooting
Common Issues
❌ Login Failed
- Verify credentials in
.envfile - Check if CAPTCHA solving is working
- Ensure university LMS is accessible
❌ CAPTCHA Not Solving
- Add Gemini API key for better accuracy
- Check internet connection
- Verify image preprocessing
❌ Session Expired
- Sessions expire after 24 hours by default
- Re-login will create a new session
- Check
SESSION_EXPIRY_HOURSsetting
❌ Browser Issues
- Ensure Chrome is installed and updated
- Check
BROWSER_HEADLESSsetting - Install required browser drivers
Debug Mode
Enable debug mode for troubleshooting:
# In .env file
DEBUG_MODE=true
SAVE_SCREENSHOTS=true
BROWSER_HEADLESS=false
🏗️ Architecture
🧱 Core Components
LMS-MCP/
├── main.py # MCP server entry point
├── lms_automation.py # Core automation logic
├── captcha_solver.py # CAPTCHA solving algorithms
├── session_manager.py # Session persistence
├── config.py # Configuration management
├── models/ # Data models
│ ├── attendance.py
│ ├── marks.py
│ └── timetable.py
└── utils/ # Utility functions
├── encryption.py
├── image_processor.py
└── web_scraper.py
🔄 Workflow
- Initialization - Load configuration and setup browser
- Authentication - Login with CAPTCHA solving
- Session Management - Save/restore login sessions
- Data Extraction - Navigate and scrape academic data
- Response Formatting - Structure data for AI consumption
🤝 Contributing
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open a Pull Request
Development Setup
# Clone your fork
git clone https://github.com/yourusername/LMS-MCP.git
cd LMS-MCP
# Install development dependencies
uv sync --dev
# Run tests
python -m pytest
# Run linting
black . && flake8 .
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
⚠️ Disclaimer
This tool is for educational purposes and personal use only. Users are responsible for:
- Complying with university policies
- Securing their own credentials
- Using the tool responsibly
- Not overloading university servers
📞 Support
- Documentation: Wiki
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Made with ❤️ for PAF-IAST students