Content
<p align="center">
<img src="./ManageBac.png" alt="ManageBac MCP Logo" width="160" />
</p>
<p align="center">
<a href="./README.md">Simplified Chinese</a> · <a href="./README.en.md">English</a>
</p>
# ManageBac MCP Server
---
> Based on [ManageBac](https://www.managebac.com/) student web interface
## Connect ManageBac to Your AI Agent
This is a local stdio MCP server that allows AI agents like Claude Code and OpenCode to read DDLs, classes, grade entries, and GPA explicitly displayed on the ManageBac website.
The default login method is manual browser login: run `npm run login` to save the session in `.managebac/storage-state.json`, and then MCP tools reuse this session. Only when `MANAGEBAC_LOGIN_MODE=password` is explicitly set, the program will attempt to automatically submit the account password.
## ✨ Features
- Get class/course list
- Read `upcoming`, `past`, and `overdue` tasks from the homepage `Tasks & Deadlines`
- View all DDLs and single-course DDLs
- View all grades and single-course grades
- Read global GPA/single-course GPA; return error if GPA is not explicitly displayed on the page
- Prohibit estimating non-weighted 4.0 GPA based on percentage or IB 1-7 scores
- Read recent N grade entries for a single course
- Read grade weights/categories for a single course
- Default manual login and session recording to reduce account lock risk
- Support automatic password login, but must be enabled manually
## 🛠️ Tool List
- `managebac_check_session`: Confirm the current session can read the student homepage
- `managebac_get_classes`: Get class/course list
- `managebac_get_all_deadlines`: View homepage Tasks & Deadlines, optional `view: upcoming | past | overdue | all`
- `managebac_get_class_deadlines`: View single-course DDLs
- `managebac_get_grades`: View all grade entries
- `managebac_get_class_grades`: Get grades for a single course
- `managebac_get_gpa`: Read explicitly displayed global GPA, return error if not found
- `managebac_get_class_gpa`: Read explicitly displayed single-course GPA, return error if not found
- `managebac_get_recent_class_grades`: Read recent N grade entries for a single course
- `managebac_get_class_grade_weights`: Read grade weights/categories for a single course
- `managebac_list_links`: List links on the logged-in page to find the exact path of a class
- `managebac_debug_snapshot`: Return the main content and links of a page for debugging
## 🚀 Installation and Usage
### Quick Installation: Copy the following commands for your AI agent
```text
Please help me install and configure 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
Then configure this MCP server as stdio:
node /absolute/path/managebac-mcp/dist/index.js
```
`npm run deploy` will ask for the ManageBac instance address. Do not hardcode a school's instance; please fill in your own instance, e.g.:
```env
MANAGEBAC_BASE_URL=https://your-school.managebac.com
```
### Manual Installation
```bash
git clone https://github.com/chiang881/managebac-mcp.git
cd managebac-mcp
npm install
npm run build
```
If Playwright cannot find Chromium on the first run:
```bash
npm run install-browser
```
Copy the configuration file:
```bash
cp .env.example .env
```
Minimum configuration:
```env
MANAGEBAC_BASE_URL=https://your-school.managebac.com
MANAGEBAC_LOGIN_MODE=manual
MANAGEBAC_STORAGE_STATE=.managebac/storage-state.json
```
After saving the configuration, open the browser to manually log in and record the session:
```bash
npm run login
```
### Automatic Password Login
By default, passwords are not submitted automatically. If automatic login is required, explicitly set in `.env` or MCP client `env`:
```env
MANAGEBAC_LOGIN_MODE=password
MANAGEBAC_EMAIL=your.email@example.com
MANAGEBAC_PASSWORD=your-password
MANAGEBAC_LOGIN_COOLDOWN_MS=900000
MANAGEBAC_LOGIN_FORCE=false
```
If the account is locked, do not repeatedly run automatic login. After confirming that the webpage can be manually logged in, run `npm run login` to re-save the session.
### Non-interactive/Headless Deployment
`npm run deploy` runs an interactive configuration wizard; non-interactive environments will report an error:
```text
Interactive terminal required. Set MANAGEBAC_BASE_URL and MANAGEBAC_LOGIN_MODE manually in non-interactive deployments.
```
There are two solutions:
1. Directly edit `.env` and write at least `MANAGEBAC_BASE_URL` and `MANAGEBAC_LOGIN_MODE=manual`
2. Pass these variables in the MCP client's `env` configuration
`.env`, `.managebac/storage-state.json`, and debugging files are ignored in `.gitignore`. Do not submit account passwords or login sessions to GitHub.
## Claude Code Configuration
Claude Code's project MCP configuration should be written in the repository root's `.mcp.json`, not `~/.claude/settings.json`:
```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"
}
}
}
}
```
After configuration, Claude Code's approval chain usually needs to be completed:
1. Allow project MCP servers in `.claude/settings.local.json`, e.g., set `enabledMcpjsonServers` or use `enableAllProjectMcpServers: true`
2. Restart Claude Code to take effect `.mcp.json` and permission configurations
3. Restart and run `/mcp`; if `managebac` is still pending, manually approve
4. When calling each MCP tool for the first time, Claude Code may also require separate allowance
## Debugging Suggestions
If DDLs or GPA are not accurately captured, first call:
```text
managebac_list_links({ "match": "task" })
managebac_list_links({ "match": "grade" })
managebac_debug_snapshot({ "path": "/student/tasks_and_deadlines?view=upcoming" })
```
Single-course DDLs are located in `Classes -> A course -> Tasks & Units -> View All Tasks`. You can pass the found class path to `managebac_get_class_deadlines` or `managebac_get_class_gpa`'s `path` parameter.
