Content
# GDMU MCP Server
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](https://playwright.dev/)
[](https://pypi.org/project/gdmu-mcp/)
AI assistants (Codex / Claude Desktop / Cursor, etc.) and Zhengfang V-9.0 educational administration system's MCP bridge - 15 tools covering the entire educational administration scene.
> 🎯 Designed specifically for **Zhengfang V-9.0 + CAS single sign-on + MFA multi-factor authentication**.
---
## Table of Contents
- [Quick Start](#quick-start)
- [Tool List (15)](#tool-list-15)
- [Configuration Instructions](#configuration-instructions)
- [AI Client Integration](#ai-client-integration)
- [Deployment](#deployment)
- [Development Guide](#development-guide)
- [Project Structure](#project-structure)
- [License](#license)
---
## Quick Start
```text
Browser login (CAS+MFA) → Save jw_session.json → MCP Server startup → AI client connection
↓
15 tools available
6 queries + 4 analysis + 4 information + 1 login
Adapted to Zhengfang V-9.0 interface
```
**One-sentence process**: First, complete CAS unified authentication (including SMS/WeChat, etc. secondary verification) with a browser, persist the Session Cookie locally, and after the MCP Server starts, automatically load the Cookie to call the educational administration API. The AI client interacts with the tools through the MCP protocol.
### Prerequisites
- Python 3.10+
- Access to the school's intranet / VPN / aTrust
- Possess an educational administration system account + available browser
- [Playwright](https://playwright.dev/) + Chromium browser engine
### 1. Installation
```bash
# Install from PyPI (recommended)
pip install gdmu-mcp
# Or install from source code
git clone https://github.com/S4saK1/gdmu_mcp.git
cd gdmu_mcp
pip install -e .
```
### 2. Browser Login
```bash
# Automatically open Chrome, complete CAS authentication (including MFA)
# Automatically save Cookie to jw_session.json after login success
python browser_login.py
```
During the process, the browser will open the CAS login page. After entering the account password and encountering secondary authentication such as SMS verification code/WeChat scan code, complete it normally. The script will automatically detect login success and extract the Cookie.
### 3. Start MCP Server
```bash
# Standard startup
python server.py
# Specify debug mode
GDMU_DEBUG=1 python server.py
```
### 4. Configure AI Client
#### Codex CLI / Claude Desktop
Add the following to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"gdmu-mcp": {
"command": "python",
"args": ["path/to/gdmu_mcp/server.py"],
"env": {
"GDMU_JW_BASE": "https://jw.gdmu.edu.cn",
"GDMU_AUTH_BASE": "https://authserver.gdmu.edu.cn"
}
}
}
}
```
#### Cursor
Add the stdio server-side in Cursor's MCP configuration.
---
## Tool List (15)
### Core Queries (6)
| Tool Name | API Endpoint | Function | Parameters |
| --- | --- | --- | --- |
| cj_tool | /cjcx/ | Query grades by semester | xnm, xqm (optional) |
| kb_tool | /kbcx/ | Query class schedule by semester | xnm, xqm |
| ks_tool | /kwgl/ | Query exam arrangements/time/location | xnm, xqm |
| grxx_tool | /xsxxxggl/ | Query complete student status | None |
| xsxyqk_tool | /xsxy/ | Query academic progress | None |
| course_select_tool | /xsxk/ | Submit course selection application | confirmed, xkkz_id, ... |
### Analysis Tools (4)
| Tool Name | Data Source | Function | Parameters |
| --- | --- | --- | --- |
| gpa_tool | cj_tool | GPA trend analysis + semester details | None |
| conflict_tool | kb_tool | Course schedule time conflict detection | xnm, xqm |
| countdown_tool | ks_tool | Exam countdown + 3-day pre-exam mark | None |
| warning_tool | xsxyqk+cj | Academic warning & failed course records | None |
### Information Queries (4)
| Tool Name | API Endpoint | Function | Parameters |
| --- | --- | --- | --- |
| cdjy_tool | /cdjy/ | Query available classrooms | xqh_id, jxl_id, xqj, jcd, zc |
| cxbm_tool | /cxbm/ | Query re-enrollment status | xnm, xqm |
| kjgl_tool | /kjgl/ | Query proficiency test management | None |
| xsjc_tool | /xsjcgl/ | Query reward and punishment records | None |
### Login Tool (1)
| Tool Name | Function | Parameters |
| --- | --- | --- |
| login_tool | CAS unified authentication login | mode (direct/vpn/atrust) |
---
## Configuration Instructions
Configure through environment variables or `.env` file:
| Variable Name | Default Value | Description |
| --- | --- | --- |
| GDMU_JW_BASE | https://jw.gdmu.edu.cn | Educational administration system address |
| GDMU_AUTH_BASE | https://authserver.gdmu.edu.cn | CAS authentication address |
| GDMU_CAS_SERVICE | {JW_BASE}/sso/jziotlogin | CAS service parameter |
| GDMU_COOKIE_PATH | ./jw_session.json | Cookie persistence path |
| GDMU_DEBUG | 0 | Debug mode switch (1=on) |
### Adapting to Other Schools
This tool is developed based on **Zhengfang V-9.0** educational administration system. If your school also uses Zhengfang V-9.0 + CAS authentication, simply modify `GDMU_JW_BASE` and `GDMU_AUTH_BASE`.
> ⚠️ **Compliance reminder**: This project is only for learning and personal self-help use. Please comply with your school's "Information System Use Regulations". Do not submit Cookie files to public repositories or share them with others.
---
## Deployment
### Method 1: PyPI Installation (Recommended)
```bash
pip install gdmu-mcp
python -m gdmu_mcp
```
### Method 2: Docker
```bash
docker build -t gdmu-mcp .
docker run -v ./jw_session.json:/app/jw_session.json gdmu-mcp
```
### Method 3: Source Code Running
```bash
git clone https://github.com/S4saK1/gdmu_mcp.git
cd gdmu_mcp
pip install -e .
python server.py
```
---
## Development Guide
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
### Quick Development
```bash
# Clone + install development dependencies
git clone https://github.com/S4saK1/gdmu_mcp.git
cd gdmu_mcp
pip install -e ".[dev]"
playwright install chromium
# Run tests
pytest
# Code inspection
ruff check .
mypy server.py browser_login.py
```
---
## Project Structure
```text
gdmu_mcp/
├── server.py # MCP Server entry
├── browser_login.py # Browser-assisted login (CAS + MFA)
├── Dockerfile # Containerized deployment
├── config.example.env # Environment variable template
├── requirements.txt # Dependency list
├── pyproject.toml # Package configuration (supports pip install gdmu-mcp)
├── CHANGELOG.md # Update log
├── CONTRIBUTING.md # Contribution guide
├── LICENSE # MIT license
├── README.md # This file
├── tests/ # Test directory
│ ├── __init__.py
│ ├── conftest.py
│ └── test_smoke.py # 18 test cases (3 basic + 15 mcp/gdmu_agent skip)
├── gdmu_mcp/ # Package directory (python -m gdmu_mcp entry)
│ ├── __init__.py
│ ├── __main__.py
│ └── server.py # Forward to root directory server.py
└── .github/
└── workflows/
├── pytest.yml # CI — Test
└── publish.yml # PyPI automatic release
```
---
## License
This project is open-sourced under the [MIT license](LICENSE). Reverse research is only for educational purposes. Please comply with your school's network usage regulations.
*Guarding every knowledge seeker's campus time with technology.*
