<p align="center"> <img src="./ManageBac.png" alt="ManageBac MCP Logo" width="160" /> </p>

<p align="center"> <a href="./README.md">简体中文</a> · <a href="./README.en.md">English</a> </p>

ManageBac MCP 服务器

---

基于 ManageBac 学生端网页实现

为您的 AI Agent 接入 ManageBac

这是一个本地 stdio MCP 服务器，可以让 Claude Code、OpenCode 等 AI Agent 读取 ManageBac 中的 DDL、class、成绩条目和页面明确显示的 GPA。

默认登录方式是手动浏览器登录：先运行 npm run login，程序会保存 .managebac/storage-state.json，之后 MCP 工具复用这个 session。只有显式设置 MANAGEBAC_LOGIN_MODE=password 时，程序才会尝试自动提交账号密码。

✨ 功能特性

• 获取 class / course 列表
• 从主页 Tasks & Deadlines 读取 upcoming、past、overdue 三个栏目
• 查看全部 DDL，以及查看单科 DDL
• 查看全部成绩，以及查看某一门 class 的成绩
• 读取全局 GPA / 单科 GPA；读不到页面明确显示的 GPA 时直接返回 error
• 禁止按百分制或 IB 1-7 成绩估算非加权 4.0 GPA
• 读取某一门课近期 N 条成绩
• 读取某一门课的成绩占比 / category weight
• 默认手动登录并记录 session，降低账号被锁风险
• 支持自动密码登录，但必须主动开启

🛠️ 工具列表

• managebac_check_session: 确认当前 session 能读取学生首页
• managebac_get_classes: 获取 class / course 列表
• managebac_get_all_deadlines: 查看主页 Tasks & Deadlines，可选 view: upcoming | past | overdue | all
• managebac_get_class_deadlines: 查看单科 DDL
• managebac_get_grades: 查看全部成绩 / 分数条目
• managebac_get_class_grades: 获取某一门 class 的成绩
• managebac_get_gpa: 读取页面明确显示的全局 GPA，读不到时返回 error
• managebac_get_class_gpa: 读取页面明确显示的单科 GPA，读不到时返回 error
• managebac_get_recent_class_grades: 读取这门 class 的近期 N 条成绩
• managebac_get_class_grade_weights: 读取这门课的成绩占比
• managebac_list_links: 列出登录后页面链接，用来找到某个 class 的精确路径
• managebac_debug_snapshot: 返回某页正文和链接，用于调试抓取规则

🚀 安装与使用

快速安装：复制以下命令给 AI agent

请帮我安装并配置 ManageBac MCP：
git clone https://github.com/chiang881/managebac-mcp.git
cd managebac-mcp
npm install
npm run build
npm run deploy
npm run login

然后把这个 MCP server 配置为 stdio：
node /absolute/path/managebac-mcp/dist/index.js

npm run deploy 会询问 ManageBac 实例地址。不要把默认实例写死成某个学校，请填写自己的实例，例如：

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

手动安装

git clone https://github.com/chiang881/managebac-mcp.git
cd managebac-mcp
npm install
npm run build

如果第一次运行 Playwright 找不到 Chromium：

npm run install-browser

复制配置文件：

cp .env.example .env

最小配置：

MANAGEBAC_BASE_URL=https://your-school.managebac.com
MANAGEBAC_LOGIN_MODE=manual
MANAGEBAC_STORAGE_STATE=.managebac/storage-state.json

保存配置后，打开浏览器手动登录并记录 session：

npm run login

自动密码登录

默认不自动提交密码。如果确实需要自动登录，在 .env 或 MCP 客户端 env 中显式设置：

MANAGEBAC_LOGIN_MODE=password
MANAGEBAC_EMAIL=your.email@example.com
MANAGEBAC_PASSWORD=your-password
MANAGEBAC_LOGIN_COOLDOWN_MS=900000
MANAGEBAC_LOGIN_FORCE=false

如果账号刚被锁定，先不要反复运行自动登录。确认网页可以手动登录后，运行 npm run login 重新保存 session。

非交互 / headless 部署

npm run deploy 会运行交互式配置向导，非交互环境会报错：

Interactive terminal required. Set MANAGEBAC_BASE_URL and MANAGEBAC_LOGIN_MODE manually in non-interactive deployments.

解决方式有两种：

1. 直接编辑 .env，至少写入 MANAGEBAC_BASE_URL 和 MANAGEBAC_LOGIN_MODE=manual
2. 在 MCP 客户端配置的 env 中传入这些变量

.env、.managebac/storage-state.json 和调试文件已经在 .gitignore 中忽略。不要把账号密码或登录态提交到 GitHub。

Claude Code 配置

Claude Code 的项目 MCP 配置应写在仓库根目录的 .mcp.json，不是 ~/.claude/settings.json：

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

配置后通常还需要完成 Claude Code 的审批链：

1. 在 .claude/settings.local.json 中允许项目 MCP server，例如设置 enabledMcpjsonServers，或使用 enableAllProjectMcpServers: true
2. 重启 Claude Code，让 .mcp.json 和权限配置生效
3. 重启后运行 /mcp，如果 managebac 仍处于 pending 状态，手动批准
4. 第一次调用每个 MCP tool 时，Claude Code 可能还会要求单独 allow

调试建议

如果 DDL 或 GPA 没抓准，先调用：

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

单科 DDL 位于 Classes -> 某门课 -> Tasks & Units -> View All Tasks。可以把找到的 class path 传给 managebac_get_class_deadlines 或 managebac_get_class_gpa 的 path 参数。