ManageBac MCP Server

一个本地 MCP 服务器，可让 AI 智能体（Claude Code、Claude Desktop、OpenCode、ChatGPT 等）读取并与你的 ManageBac 账号交互：截止日期、成绩、公告、资源和作业提交。

它通过真实的浏览器窗口登录（你只需登录一次），在本地保存会话并复用它——你的密码永远不会被存储或发送到任何地方。

工具

• managebac_get_classes — 列出你的课程

• managebac_get_all_deadlines / managebac_get_class_deadlines — 即将到来、已过期和逾期的任务

• managebac_get_grades / managebac_get_class_grades / managebac_get_recent_class_grades — 成绩记录

• managebac_get_gpa / managebac_get_class_gpa — 页面显示的 GPA（绝不做估算）

• managebac_get_class_grade_weights — 课程的成绩类别权重

• managebac_get_announcements — 来自学校和课程页面的公告/通知

• managebac_get_class_resources — 课程的可下载文件/资源（课堂作业、资料）

• managebac_download_file — 以 base64 形式下载文件（附件或资源 href）

• managebac_get_assignment_details — 某个作业的评分标准、说明和附件

• managebac_submit_assignment — 为作业附加文件（来自磁盘；对于 ChatGPT 等无法访问本地文件的客户端，可使用 base64）或文本；始终先进行试运行

• managebac_get_cas_info / managebac_get_ee_info — CAS/拓展论文反思，解锁后可用

• managebac_check_session / managebac_runtime_info — 会话健康状态和进程诊断

• managebac_list_links / managebac_debug_snapshot — 用于查找页面路径的调试辅助工具

公告和资源的获取是尽力而为的：ManageBac 的页面结构因学校而异，因此如果结果看起来很少，可以请智能体使用 managebac_list_links 或 managebac_debug_snapshot 找到正确的页面，并将其作为 path 传入。

Related MCP server: Chrome MCP Server

安装

需要 Node.js 20 以上版本。

git clone https://github.com/DH4410/managebac-mcp-server.git
cd managebac-mcp-server
npm install
npm run build
npm run install-browser   # first time only, installs Chromium for Playwright

复制 env 文件，并设置你学校的 ManageBac URL：

cp .env.example .env

MANAGEBAC_BASE_URL=https://your-school.managebac.com

登录一次（会打开真实的浏览器窗口，保存会话，然后关闭）：

npm run login

连接到你的 AI 智能体

大多数 MCP 客户端（Claude Code、Claude Desktop、OpenCode、Cursor）会将 MCP 服务器作为本地进程运行。在它们的 MCP 配置中添加类似下面的内容：

{
  "mcpServers": {
    "managebac": {
      "command": "node",
      "args": ["/absolute/path/to/managebac-mcp-server/dist/index.js"],
      "env": {
        "MANAGEBAC_BASE_URL": "https://your-school.managebac.com",
        "MANAGEBAC_STORAGE_STATE": "/absolute/path/to/managebac-mcp-server/.managebac/storage-state.json"
      }
    }
  }
}

对于 Claude Code，请将上述内容放在仓库根目录的 .mcp.json 中，然后运行 /mcp 并批准该服务器。

连接到 ChatGPT

ChatGPT 只能通过 URL（而非本地进程）连接 MCP 服务器，因此你的本地服务器需要一个临时的公共 URL 和一个密钥令牌来保护它。你的 ManageBac 登录信息依然永远不会离开你的机器——只有工具响应会通过隧道传输，而且仅在你使用期间。

最快的方式——一条命令：

npm install cloudflared   # one-time; downloads the cloudflared binary (~40MB)
npm run chatgpt

这条命令会构建服务器，以 HTTP 模式启动它，打开一条 Cloudflare 快速隧道，并打印出类似下面的内容块：

=================================================
 ChatGPT connector settings
=================================================
 URL:   https://random-words.trycloudflare.com/mcp
 Auth:  Bearer token
 Token: 9f2a1c...
=================================================

在 ChatGPT 中：设置 → 连接器 → 高级/开发者模式 → 添加连接器，然后粘贴 URL，并使用打印出的令牌将认证方式设置为 Bearer token。

在你想让 ChatGPT 访问期间，请保持终端打开——关闭终端（或按 Ctrl+C）会同时停止隧道和服务器。URL 和令牌在每次运行命令时都是新的，因此重启后需要将它们重新粘贴到 ChatGPT 中。

手动方式（如果你不想添加 cloudflared 包）：在 .env 中设置 MCP_TRANSPORT=http、MCP_HTTP_PORT=3939 和 MCP_HTTP_TOKEN=<a long random value>，运行 npm start，然后将任意 HTTPS 隧道工具指向 3939 端口（例如，如果你已经单独安装了 cloudflared，可以使用 cloudflared tunnel --url http://localhost:3939），并以同样的方式在 ChatGPT 中使用 <tunnel-url>/mcp 加上你的令牌。

注意事项

• .env 和 .managebac/（你保存的会话）已被 git 忽略——切勿提交它们。

• 如果你修改了代码或重新登录，请重启 MCP 客户端，以便它加载新的进程。

• 如果 ManageBac 锁定了你的账号，请停止重试自动登录，改用 npm run login（手动登录）。

故障排查

如果截止日期或 GPA 看起来不正确，请使用调试工具查看抓取器实际找到了什么：

managebac_list_links({ "match": "task" })
managebac_debug_snapshot({ "path": "/student/tasks_and_deadlines?view=upcoming" })

可选：自动密码登录

默认关闭（手动登录更安全）。如需启用，请在 .env 中设置：

MANAGEBAC_LOGIN_MODE=password
MANAGEBAC_EMAIL=your.email@example.com
MANAGEBAC_PASSWORD=your-password