hanifisenturk/sabis-mcp-server

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

1. Clone the repository:

   git clone https://github.com/your-username/sabis-mcp-server.git
   cd sabis-mcp-server
   

2. Install dependencies:

   npm install
   

3. Set up environment variables: Create a .env file in the root directory:

   USERNAME=your_sabis_username
   PASSWORD=your_sabis_password
   

4. Build the project:

   npm run build
   

⚙️ Configuration

Environment Variables

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 USERNAME and PASSWORD are set
• Check .env file 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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the ISC License - see the 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.