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

# ManageBac MCP Server

A local MCP server that lets AI agents (Claude Code, Claude Desktop, OpenCode, ChatGPT, etc.) read and interact with your [ManageBac](https://www.managebac.com/) account: deadlines, grades, announcements, resources, and assignment submission.

It logs in through a real browser window (you sign in once), saves the session locally, and reuses it — your password is never stored or sent anywhere.

## Tools

- `managebac_get_classes` — list your classes
- `managebac_get_all_deadlines` / `managebac_get_class_deadlines` — upcoming, past, and overdue tasks
- `managebac_get_grades` / `managebac_get_class_grades` / `managebac_get_recent_class_grades` — grade entries
- `managebac_get_gpa` / `managebac_get_class_gpa` — GPA as shown on the page (never estimated)
- `managebac_get_class_grade_weights` — category weighting for a class
- `managebac_get_announcements` — announcements/notices from the school and class pages
- `managebac_get_class_resources` — downloadable files/resources (classwork, materials) for a class
- `managebac_download_file` — download a file (an attachment or resource href) as base64
- `managebac_get_assignment_details` — rubric, instructions, and attachments for one assignment
- `managebac_submit_assignment` — attach a file (from disk, or base64 for clients like ChatGPT without local file access) or text to an assignment; always dry-runs first
- `managebac_get_cas_info` / `managebac_get_ee_info` — CAS/Extended Essay reflections, once unlocked
- `managebac_check_session` / `managebac_runtime_info` — session health and process diagnostics
- `managebac_list_links` / `managebac_debug_snapshot` — debugging helpers for finding page paths

Announcements and resources are best-effort: ManageBac's page structure varies by school, so if results look thin, ask the agent to use `managebac_list_links` or `managebac_debug_snapshot` to find the right page and pass it as `path`.

## Install

Requires Node.js 20+.

```bash
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
```

Copy the env file and set your school's ManageBac URL:

```bash
cp .env.example .env
```

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

Log in once (opens a real browser window, saves the session, then closes):

```bash
npm run login
```

## Connect it to your AI agent

Most MCP clients (Claude Code, Claude Desktop, OpenCode, Cursor) run MCP servers as a local process. Add something like this to their MCP config:

```json
{
  "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"
      }
    }
  }
}
```

For Claude Code specifically, put this in `.mcp.json` at the repo root, then run `/mcp` and approve the server.

## Connect it to ChatGPT

ChatGPT only connects to MCP servers over a URL (not a local process), so your local server needs a temporary public URL and a secret token to protect it. Your ManageBac login still never leaves your machine — only the tool responses cross the tunnel, and only while you're using it.

**Quickest path — one command:**

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

This builds the server, starts it in HTTP mode, opens a Cloudflare quick tunnel, and prints a block like:

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

In ChatGPT: **Settings → Connectors → Advanced/Developer mode → Add connector**, then paste the URL and set Authentication to Bearer token with the printed token.

Keep the terminal open while you want ChatGPT to have access — closing it (or Ctrl+C) stops both the tunnel and the server. The URL and token are new every time you run the command, so re-paste them into ChatGPT after a restart.

**Manual path** (if you'd rather not add the `cloudflared` package): set `MCP_TRANSPORT=http`, `MCP_HTTP_PORT=3939`, and `MCP_HTTP_TOKEN=<a long random value>` in `.env`, run `npm start`, then point any HTTPS tunnel tool (e.g. `cloudflared tunnel --url http://localhost:3939` if you already have `cloudflared` installed separately) at port 3939 and use `<tunnel-url>/mcp` + your token in ChatGPT the same way.

## Notes

- `.env` and `.managebac/` (your saved session) are git-ignored — never commit them.
- If you edit the code or re-login, restart your MCP client so it picks up the new process.
- If ManageBac locks your account, stop retrying automatic login and use `npm run login` (manual) instead.

## Troubleshooting

If deadlines or GPA look wrong, use the debug tools to see what the scraper is finding:

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

## Optional: automatic password login

Off by default (manual login is safer). To enable, set in `.env`:

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