eClass MCP Server

Features

Authentication: Log in to eClass through UoA's CAS SSO authentication system
Course Management: Retrieve lists of enrolled courses
Session Management: Maintain authenticated sessions between tool calls
Status Checking: Verify authentication status

Project Structure

This project follows a modular architecture for better maintainability:

eclass-mcp-server/
├── run_server.py               # Entry point script for running the server
├── pyproject.toml              # Project configuration and dependencies
├── .env                        # Environment variables (create from example.env)
├── src/
    └── eclass_mcp_server/      # Main package
        ├── __init__.py         # Package initialization
        ├── server.py           # Core server implementation and tool handlers
        ├── authentication.py   # Authentication functionality 
        ├── course_management.py # Course-related functionality
        ├── html_parsing.py     # HTML parsing utilities
        └── test/               # Test scripts for functionality verification
            ├── __init__.py
            ├── test_login.py
            ├── test_courses.py
            └── run_all_tests.py

Installation

Install the server using UV (recommended):

# Clone the repository
git clone https://github.com/yourusername/eClass-MCP-server.git
cd eClass-MCP-server

# Install dependencies
uv sync --dev --all-extras

Alternatively, install with pip:

pip install -e .

Configuration

Create a .env file in the root directory with the following configuration (or copy and rename the provided example.env file):

ECLASS_URL=https://eclass.uoa.gr
ECLASS_USERNAME=your_username
ECLASS_PASSWORD=your_password

All credentials must be provided in the .env file. The server does not accept credentials as parameters.

Usage

Terminal

Run the server using the entry point script:

python run_server.py

Or as a module:

python -m src.eclass_mcp_server.server

Cursor

Go to Settings -> MCP. Click on Add new MCP server:

Select a unique but appropriate name so that the Agent knows what the server is for (e.g., "eClass Server")
Select the command option on "Type"
Add this in the command input: python /path/to/eclass-mcp-server/run_server.py

This command runs the run_server.py script that connects the MCP Client with the main server entry point in server.py.

Claude Desktop

To use with Claude Desktop:

Open Claude Desktop
Go to Settings > Server
Add a new server with the following details:
- Name: eClass MCP
- Command: Path to your run_server.py script
Click Add Server
Select the server from the dropdown when chatting with Claude

Tools

The server provides the following tools for use with MCP clients:

{
  "random_string": "any_value"
}

get_courses

Retrieve a list of enrolled courses (requires login first).

{
  "random_string": "any_value"
}

logout

Log out from eClass.

{
  "random_string": "any_value"
}

authstatus

Check the current authentication status.

{
  "random_string": "any_value"
}

Testing

The project includes test scripts to verify functionality:

# Run all tests
python -m src.eclass_mcp_server.test.run_all_tests

# Run specific tests
python -m src.eclass_mcp_server.test.test_login
python -m src.eclass_mcp_server.test.test_courses

Example MCP Client Usage

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import asyncio

async def run_agent():
    server_params = StdioServerParameters(
        command="python /path/to/eclass-mcp-server/run_server.py",
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize the session
            await session.initialize()
            
            # Login to eClass
            login_result = await session.call_tool("login", {
                "random_string": "dummy"
            })
            print(login_result)
            
            # Get courses
            courses_result = await session.call_tool("get_courses", {
                "random_string": "dummy"
            })
            print(courses_result)
            
            # Logout
            logout_result = await session.call_tool("logout", {
                "random_string": "dummy"
            })
            print(logout_result)

if __name__ == "__main__":
    asyncio.run(run_agent())

Integration with AI Agents

This MCP server is designed to be used with AI agents that support the Model Context Protocol. This enables AI systems to interact with eClass directly, allowing for capabilities like:

Retrieving course information
Checking course announcements
Accessing course materials
Submitting assignments (future feature)

Security Considerations

The server handles sensitive authentication credentials
Credentials are only used for authentication and are not stored persistently
Session cookies are maintained in memory during the server's lifecycle
The server validates session state before performing operations
The .env file with credentials should never be committed to version control (it's included in .gitignore)

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Integrations