Managebac

ManageBac MCP Server

A local MCP server that lets AI agents (Claude Code, Claude Desktop, OpenCode, ChatGPT, etc.) read and interact with your ManageBac 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+.

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:

cp .env.example .env

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

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

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:

{
  "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:

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:

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:

MANAGEBAC_LOGIN_MODE=password
[email protected]
MANAGEBAC_PASSWORD=your-password