Skip to main content
Glama
chaoxing-mcp

chaoxing-mcp

by OSSKn4w7

cxmcp — 学习通 MCP Server(教师版 / 学生版)+ 配套 Skills

参考 Cr-GH0/chaoxing-agent 与 Aemiser/chaoxing_mcp 的逆向成果自研的 超星学习通 MCP server。纯 HTTP 协议模拟,无浏览器、无 WebDriver、无油猴依赖。

⚠️ 使用声明

  • 本项目为学习通平台第三方协议实现,平台改版可能导致功能失效;

  • 视频/测验自动化能力默认关闭,开启后可能违反平台条款与所在院校学术规范, 存在成绩无效、账号处罚风险,后果自负;

  • 密码仅在登录调用内存中使用;Cookie 以 0600 权限存本地 JSON。

Related MCP server: zju-mcp

组成

目录

说明

chaoxing-mcp/

MCP server 包,双入口 cx-mcp-teacher / cx-mcp-student

chaoxing-teacher-skill/

WorkBuddy/CodeBuddy 教师版 Skill 插件

chaoxing-student-skill/

WorkBuddy/CodeBuddy 学生版 Skill 插件

工具规模:共用 5 + 教师 12 + 学生 11;学生版加 --enable-automation 追加 2 个自动化工具。

安装

cd chaoxing-mcp
pip install -e .            # 或 uv pip install -e .
cx-mcp-student --help       # 验证入口

接入宿主(stdio,即插即用)

{
  "mcpServers": {
    "chaoxing-teacher": {
      "command": "cx-mcp-teacher",
      "env": { "CX_COOKIE_FILE": "~/.chaoxing-mcp/teacher_cookies.json" }
    },
    "chaoxing-student": {
      "command": "cx-mcp-student",
      "env": { "CX_COOKIE_FILE": "~/.chaoxing-mcp/student_cookies.json" }
    }
  }
}
  • 远程模式:cx-mcp-student --transport streamable-http --host 127.0.0.1 --port 8000 (不要绑定公网)

  • 自动化(学生版):cx-mcp-student --enable-automation 或环境变量 CX_ENABLE_AUTOMATION=1

登录方式

  1. 账号密码:cx_login(登录页 t=true 时走 AES-CBC 加密提交 /fanyalogin)。 平台要求短信/二次验证时返回 login_verification_required,不绕过。

  2. Cookie 导入:浏览器登录学习通 → F12 → 复制 Cookie(uid/_uid/fid/vc3 等)→ cx_import_cookies 传入 [{name, value, domain, path}]。

安全设计(借鉴 chaoxing-agent)

  • 两阶段确认:批改/发通知/发起签到/上传/正式提交/自动化操作,首次调用返回 confirmation_required + 一次性令牌(SHA-256 参数指纹绑定,5 分钟 TTL), 参数变化即失效,防重放、防 TOCTOU;

  • 风控即暂停:HTTP 202 / antispider 跳转 → 返回 risk_control_paused 与指引, 不自动过验证码;

  • 回读验证:提交类操作以刷新列表核对状态为准,HTTP 200 不等于成功;

  • 日志全部走 stderr,stdout 仅承载 MCP stdio 协议。

实机校准(重要)

本仓库协议实现基于参考项目的公开逆向知识 + mock 单测(23 个,全绿), 未在真实学习通账号上验证。上线前请先跑:

python smoke_test.py login --role student --username 手机号 --password 密码

登录与课程列表属高确定性端点;签到/成绩/通知/上传/自动化端点随平台模板变动, 失败时会返回候选端点探测记录,按记录抓包更新 src/cxmcp/api/ 中对应 URL 即可。

开发

pip install -e ".[dev]"
pytest tests/ -q

目录

src/cxmcp/
├── config.py      # 环境变量/CLI 配置
├── crypto.py      # 登录 AES-CBC(固定 TRANSFER_KEY)
├── session.py     # 会话/Cookie 原子持久化/TLS 兼容/风控守卫
├── confirm.py     # 两阶段确认令牌
├── api/           # courses / chapters / work / files / exams / signin / teacher / automation
├── tools/         # MCP 工具注册(common / teacher / student / automation)
├── server.py      # build_server(role, enable_automation)
└── cli.py         # stdio / streamable-http 双传输入口

许可

MIT。与超星官方无关联。

Available Tools

16 tools
cx_import_cookiesA

从浏览器导入学习通 Cookie(登录后 F12 复制,或用编辑器插件导出)。传入 [{name,value,domain?,path?}, ...]。适用于平台强制二次验证、密码登录被风控等场景。

Inputs: cookies (required). Returns: object

cx_list_coursesA

列出学习通课程(学生返回『我学的课』,教师返回任教课程),含 courseId/clazzId/cpi——后续所有课程相关操作都靠这三个 ID 定位。

Inputs: no named parameters. Returns: object

cx_loginA

登录学习通(超星账号)。密码仅在本次调用内存中使用,不会写入日志或返回值。若平台要求二次验证(短信/扫码),会返回 login_verification_required,此时请引导用户浏览器登录后改用 cx_import_cookies。

Inputs: password (required), username (required). Returns: object

cx_logoutA

退出学习通并删除本地 Cookie 文件。

Inputs: no named parameters. Returns: object

cx_s_download_attachmentC

下载作业/资料附件到本地(objectId 定位)。

Inputs: saveDir (required), objectId (required). Returns: object

cx_s_download_materialC

按 objectId 下载课程资料(getYunFiles 直链优先)。

Inputs: saveDir (required), objectId (required). Returns: object

cx_session_statusA

检查学习通登录态是否有效(回读个人空间首页判断)。

Inputs: no named parameters. Returns: object

cx_s_get_homework_detailA

读取作业详情:题目列表(题干/选项/题型)、附件列表、standardEnc。不会自动作答或提交。

Inputs: workUrl (required), courseRef (required). Returns: object

cx_s_get_study_recordsC

查看课程学习记录(菜单『学习记录/统计』页解析)。

Inputs: courseRef (required). Returns: object

cx_s_list_chaptersB

列出课程章节树(章节名/链接)。

Inputs: courseRef (required). Returns: object

cx_s_list_examsA

列出课程考试(标题/状态/入口链接)。只读取,不进入答题。

Inputs: courseRef (required). Returns: object

cx_s_list_homeworksB

列出课程作业(标题/状态/时间/详情链接)。

Inputs: courseRef (required). Returns: object

cx_s_list_learning_coursesA

列出『我学的课』(courseId/clazzId/cpi/教师名),后续操作用这些 ID 定位。

Inputs: no named parameters. Returns: object

cx_s_list_materialsA

列出课程『资料』目录的文件(名称/objectId)。

Inputs: courseRef (required). Returns: object

cx_s_sign_inA

学生签到:normal(一键)/location(位置)/code(签到码)/photo(拍照)。

Inputs: activityId (required), code, address, latitude, +3 more. Returns: object

cx_s_submit_homeworkA

作业作答:submit=false 为暂存(安全);submit=true 为正式提交(★高影响,首次调用返回 confirmToken,确认后携带 token + 同参数重调)。answers 格式: [{"stem":"题干关键词","answer":"A"}]。

Inputs: answers (required), workUrl (required), courseRef (required), submit, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 16 tools

    Disambiguation3/5

    Most tools have clearly scoped purposes, but cx_s_list_learning_courses and cx_list_courses overlap heavily for student course listing, and cx_s_download_material vs cx_s_download_attachment both perform objectId-based downloads from different sources. Descriptions help clarify the intended resource, but an agent could still misselect between these pairs.

    Naming Consistency4/5

    The set largely follows a verb_noun pattern with a consistent cx_s_ prefix for student operations and cx_ for auth/session operations. Minor inconsistencies exist: cx_session_status is noun-style, cx_s_list_learning_courses vs cx_list_courses use different names for similar listing actions, and material/materials singular/plural are mixed.

    Tool Count4/5

    16 tools is at the upper edge but still reasonable for a platform server covering auth, courses, chapters, materials, homework, exams, sign-in, and downloads. There is some redundancy that could be trimmed, but no tool feels entirely out of place.

    Completeness4/5

    The server covers the main student workflows: login/session management, course listing, content/material access, homework reading and submission, sign-in, and exam listing. The most notable gap is that exams are read-only with no submission workflow, but the core learning-assistant surface is otherwise coherent.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables interaction with Zhejiang University's learning platform (学在浙大 / 智云课堂) via MCP tools, allowing natural language commands to check todos, view schedules, fetch lecture transcripts, and submit homework.
      7
      9
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to read and manipulate ZSXQ (知识星球) content via MCP, allowing listing groups, searching posts, downloading and summarizing content through natural language.
      9
      MIT