SABIS MCP Server 🎓
A Model Context Protocol (MCP) Server for accessing academic grades from the Sakarya University SABIS (Student Information System). This server enables AI assistants and applications to securely retrieve student academic information through automated web scraping.
🌟 Features
- 🔐 Secure Authentication: Uses environment variables for credentials
- 📊 Comprehensive Grade Retrieval: Fetches detailed academic information including:
- Course codes and names
- Assessment types (Midterm, Quiz, Assignments, Projects, Finals)
- Grade percentages and weights
- Final letter grades
- Academic year and semester information
- 🤖 MCP Integration: Compatible with Claude, Cursor, and other MCP-enabled AI assistants
- 🚀 Headless Browser Automation: Uses Puppeteer for reliable web scraping
- ⚡ Real-time Data: Fetches live data directly from SABIS system
🛠️ Technology Stack
- TypeScript - Type-safe development
- Puppeteer - Web scraping and browser automation
- Model Context Protocol SDK - MCP server implementation
- Node.js - Runtime environment
📋 Requirements
- Node.js 18+
- TypeScript 5.8+
- Valid SABIS credentials (Sakarya University student account)
🚀 Installation
-
Clone the repository:
git clone https://github.com/your-username/sabis-mcp-server.git cd sabis-mcp-server -
Install dependencies:
npm install -
Set up environment variables: Create a
.envfile in the root directory:USERNAME=your_sabis_username PASSWORD=your_sabis_password -
Build the project:
npm run build
⚙️ Configuration
Environment Variables
| Variable | Description | Required |
|---|---|---|
USERNAME | Your SABIS student ID/username | ✅ Yes |
PASSWORD | Your SABIS account password | ✅ Yes |
MCP Client Setup
You have two options for configuring credentials with your MCP client:
Option 1: Environment Variables in MCP Configuration
Add the server to your MCP client configuration with credentials directly in the config:
{
"mcpServers": {
"sabis-mcp-server": {
"command": "node",
"args": [
"/path/to/sabis-mcp-server/build/index.js"
],
"env": {
"USERNAME": "your_student_number",
"PASSWORD": "your_password"
}
}
}
}
Option 2: Using .env File
Alternatively, create a .env file in the project directory and remove the env property from the MCP configuration:
Create .env file:
USERNAME=your_student_number
PASSWORD=your_password
MCP Configuration:
{
"mcpServers": {
"sabis-mcp-server": {
"command": "node",
"args": [
"/path/to/sabis-mcp-server/build/index.js"
]
}
}
}
💡 Tip: Option 1 is more convenient for MCP clients like Cursor, while Option 2 is better for keeping credentials separate from configuration files.
🎯 Usage
Once configured, you can use the MCP server with compatible AI assistants:
Available Tools
get-grades
Retrieves academic grades from SABIS system.
Example Usage:
// Through MCP-enabled AI assistant
"Get my grades from SABIS"
Response Format:
Login successful! 🎓
Academic Year: 2024 - Semester: Bahar
=== SWE310 - MOBİL UYGULAMA GELİŞTİRME ===
Grup: 1. Öğretim A Grubu
• Ara Sınav (45%): 95
• Ödev (5%): 100
• Final (50%): 85
📋 Final Grade: AA
🔧 Development
Running in Development Mode
# Install dependencies
npm install
# Build the project
npm run build
# Test the server
node build/index.js
Project Structure
sabis-mcp-server/
├── src/
│ └── index.ts # Main MCP server implementation
├── build/ # Compiled JavaScript output
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
└── README.md # This file
Key Components
- MCP Server Setup: Configured using
@modelcontextprotocol/sdk - Authentication: Environment-based credential management
- Web Scraping: Puppeteer-based automation for SABIS portal
- Data Extraction: DOM parsing for grade information
- Error Handling: Comprehensive error management and logging
🛡️ Security & Privacy
- Credentials: Stored securely in environment variables
- Headless Operation: No UI exposure of sensitive information
- HTTPS: All communication with SABIS uses secure connections
- No Data Storage: Grades are fetched in real-time, not stored locally
- Session Management: Browser sessions are properly cleaned up
🚨 Troubleshooting
Common Issues
"Username and password are required"
- Ensure environment variables
USERNAMEandPASSWORDare set - Check
.envfile exists and contains correct credentials
"Login failed"
- Verify SABIS credentials are correct
- Check if SABIS portal is accessible
- Ensure university network access if required
Browser/Puppeteer errors
- Install Chromium dependencies on Linux:
sudo apt-get install -y libgbm-dev libnss3-dev libxss1 libasound2
📚 API Reference
Tools
get-grades
Authenticates with SABIS and retrieves academic grade information.
Parameters: None (uses environment variables)
Returns:
- Academic year and semester
- Course information with grades
- Assessment breakdown with percentages
- Final grades where available
🤝 Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📄 License
This project is licensed under the ISC 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 terms of service
- Protecting their account credentials
- Using the tool responsibly and ethically
The developers are not responsible for any misuse or consequences arising from the use of this software.
👨💻 Author
Mehmet Hanifi Şentürk
🔗 Related Projects
- Model Context Protocol - Official MCP documentation
- Puppeteer - Browser automation library
- Claude MCP Integration - Using MCP with Claude
Note: This is an unofficial tool and is not affiliated with Sakarya University or the official SABIS system.