🎓 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

1. Clone the repository:

   git clone <your-repo-url> cd LMS-MCP

2. Install dependencies:

   # Using uv (recommended) uv sync # Or using pip pip install -e .

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

🔑 Getting Google Gemini API Key (Optional but Recommended)

1. Visit Google AI Studio

2. Sign in with your Google account

3. Click "Create API Key"

4. Copy the API key to your .env file

🔧 Setup with AI Assistants

🤖 Claude Desktop Setup

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

2. 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" } } } }

3. Restart Claude Desktop

4. Test the connection:

   Can you check my LMS attendance?

💻 Cursor IDE Setup

1. Open Cursor IDE

2. Go to Settings (Ctrl/Cmd + ,)

3. Navigate to Extensions → MCP

4. Add new MCP server:

   { "name": "LMS Automation", "command": "python", "args": ["./main.py"], "cwd": "/path/to/LMS-MCP", "env": { "PYTHONPATH": "/path/to/LMS-MCP" } }

5. Restart Cursor

6. Test in chat:

   @lms-automation login to LMS and check my marks

🆚 VS Code with GitHub Copilot Setup

1. Install MCP Extension:

   • Open VS Code

   • Go to Extensions (Ctrl+Shift+X)

   • Search for "MCP Client" and install

2. Configure MCP server:

   Create .vscode/settings.json in your project:

   { "mcp.servers": [ { "name": "lms-automation", "command": "python", "args": ["main.py"], "cwd": "${workspaceFolder}", "env": { "PYTHONPATH": "${workspaceFolder}" } } ] }

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

• logout_lms - Logout and clear session

📊 Academic Data

• check_attendance - Get attendance records by subject

• get_marks - Retrieve marks and grades

• get_timetable - Access class schedule

📝 Applications

• create_application - Submit university applications

• view_application_status - Check application status

🔧 Utilities

• solve_captcha - Manual CAPTCHA solving

💡 Usage Examples

Basic Login and Data Retrieval

Advanced Queries

🔍 Troubleshooting

Common Issues

❌ Login Failed

• Verify credentials in .env file

• 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_HOURS setting

❌ Browser Issues

• Ensure Chrome is installed and updated

• Check BROWSER_HEADLESS setting

• Install required browser drivers

Debug Mode

Enable debug mode for troubleshooting:

🏗️ Architecture

🧱 Core Components

🔄 Workflow

1. Initialization - Load configuration and setup browser

2. Authentication - Login with CAPTCHA solving

3. Session Management - Save/restore login sessions

4. Data Extraction - Navigate and scrape academic data

5. Response Formatting - Structure data for AI consumption

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit changes (git commit -m 'Add amazing feature')

4. Push to branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Development Setup

📄 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

⭐ Star this repo | 🐛 Report Bug | 💡 Request Feature