qldt-hanu-mcp

Model Context Protocol (MCP) server for QLDT HANU — the student management system of Hanoi University (qldt.hanu.edu.vn). Enables your AI assistants to authenticate and directly interact with the university portal.

🚀 Quick Start

1. Build the Server

git clone https://github.com/qxbao/qldt-hanu-mcp.git
cd qldt-hanu-mcp
pnpm install
pnpm run compile

2. Configure Your IDE

Add the following to your MCP configuration file:

Edit ~/.gemini/settings.json or your project's .gemini/settings.json:

{
  "mcpServers": {
    "qldt-hanu-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/qldt-hanu-mcp/build/src/index.js"],
      "env": {
        "QLDT_USERNAME": "your_student_id",
        "QLDT_PASSWORD": "your_password"
      }
    }
  }
}

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "qldt-hanu-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/qldt-hanu-mcp/build/src/index.js"],
      "env": {
        "QLDT_USERNAME": "your_student_id",
        "QLDT_PASSWORD": "your_password"
      }
    }
  }
}

Edit .vscode/mcp.json in your workspace:

{
  "servers": {
    "qldt-hanu-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/qldt-hanu-mcp/build/src/index.js"],
      "env": {
        "QLDT_USERNAME": "your_student_id",
        "QLDT_PASSWORD": "your_password"
      }
    }
  }
}

Edit .cursor/mcp.json:

{
  "mcpServers": {
    "qldt-hanu-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/qldt-hanu-mcp/build/src/index.js"],
      "env": {
        "QLDT_USERNAME": "your_student_id",
        "QLDT_PASSWORD": "your_password"
      }
    }
  }
}

Note: Replace /absolute/path/to/qldt-hanu-mcp with the actual path where you cloned the repository. The env block is optional — see Authentication for details.

3. Start Using

Ask your AI assistant to:

• "Login to QLDT for me with: xxxxxxx - [PASSWORD]" (not needed if env vars are set)

• "Check my info on QLDT"

• "Check token readiness"

• "What is my schedule for semester 1 of 2023?"

• "Check my tuition fee status"

• "Check my academic grades"

🛠️ Available Tools

Tool Details

login

Authenticate with the QLDT system. Both parameters are optional if QLDT_USERNAME and QLDT_PASSWORD environment variables are configured — the server will fall back to them automatically.

get_session_status

Check whether the server currently holds a valid authentication token. No parameters required.

get_student_info

Fetch the authenticated student's profile. Returns data in Vietnamese, including:

• Personal info (name, date of birth, gender, ethnicity, etc.)

• Academic info (class, major, faculty, academic year)

• Contact info (phone, email, address)

• Advisor info (name, phone, email)

• Enrollment status

get_student_schedule

Fetch the student's schedule for a specific academic year and semester. Returns data in Vietnamese.

get_all_semester_tuition_fee

Fetch the student's tuition fee statuses across all semesters. Returns data in Vietnamese. No parameters required.

get_all_semester_grades

Fetch the student's academic grades and GPA across all semesters. Returns data in Vietnamese. No parameters required.

🧑‍💻 Development

Prerequisites

• Node.js ≥ 18

• pnpm (recommended) or npm

Setup

# Install dependencies
pnpm install

# Compile TypeScript
pnpm run compile

# Run tests
pnpm test

# Lint
pnpm run lint

# Auto-fix lint issues
pnpm run fix

Tech Stack

🔐 Authentication

The server supports two authentication modes:

Mode 1 — Manual (via AI prompt): Ask your AI assistant to log in. Credentials are only used for the login request and are never stored.

Mode 2 — Auto-login (via Environment Variables): Set QLDT_USERNAME and QLDT_PASSWORD in the MCP server's env config block. The server will automatically authenticate on startup without any user prompt.

Session Persistence

After a successful login, the access token is saved to a local .session.json file in the server's working directory. On the next startup, the server loads from this file automatically — avoiding the need to log in again after an IDE restart, as long as the token has not expired.

• Session TTL: 1 hour from last successful login.

• Storage: Local .session.json file (add to .gitignore if needed).

🔒 Security

• Credentials are transmitted directly to QLDT's official authentication endpoint over HTTPS.

• Access tokens are cached to .session.json for up to 1 hour, then invalidated automatically.

• The server uses a randomized User-Agent for each session.

• Plaintext credentials are never stored — only the resulting access token is persisted.

📋 Roadmap

• Course schedule retrieval

• Grade / transcript lookup

• Tuition fee status

• Course registration

🤝 Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

1. Fork the repository

2. Create your 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 GNU General Public License v2.0 — see the LICENSE file for details.

Disclaimer: This is an unofficial, community-driven project. It is not affiliated with or endorsed by Hanoi University. Use at your own discretion.