Anteater MCP

Anteater MCP

Release 1.0.0-beta.3 returns structured error codes from every tool and from the REST facade, so clients can tell a rejected API key from a rate limit or an upstream outage. See Changes for the REST response change.

An MCP server that lets Claude and ChatGPT help you pick classes at UC Irvine.

It wraps Anteater API — UCI's course catalogue, the live schedule of classes (WebSoc), historical grade distributions, enrollment history, prerequisite trees, AP credit, degree requirements and supplementary RMP ratings — and exposes them as 20 tools, 6 guided prompts and 4 reference resources, shaped around the questions students actually ask.

Zero runtime dependencies. Run the source with Node 24 LTS, or download a standalone Linux, macOS or Windows executable that already contains the same Node runtime.

"Find me a GE-2 for Fall that ends before 5pm and still has seats, ranked by how well people do."
Course        Title                Units  GPA   A%   n     SeatsOpen  Example meeting------------  -------------------  -----  ----  ---  ----  ---------  ---------------------------BIO SCI 17    EVO PSYCHOLOGY       4      3.80  88%  2410  2          TuTh 15:30-16:50 @ SH 134UNI STU H30A  ANALYSIS HEALTH LIT  4      3.77  84%  864   15         TuTh 12:30-13:50 @ ALP 1600LPS 31        INTRO INDUCT LOGIC   4      3.61  80%  2108  11         TuTh 14:00-15:20 @ EH 1200

Quickstart

git clone https://github.com/KKazuhaK/Anteater-MCP.gitcd anteater-mcpnode --version                         # Node 24 LTSnode anteater-mcp.mjs --list-tools     # confirm it runs

Then add it to your client — Claude Desktop, Claude Code, ChatGPT, or any other MCP client.

Nothing else is required. An API key is optional but recommended.

Installing

Standalone binary

Each GitHub Release contains native archives for Linux, macOS and Windows on amd64 and arm64, plus SHA256SUMS.txt. These do not require Node.js:

# After downloading and extracting the archive for your platform:./anteater-mcp --version./anteater-mcp --list-tools

In an MCP client configuration, use the absolute path to anteater-mcp (or anteater-mcp.exe) as command and omit the args array. macOS archives are ad-hoc signed; public Developer ID signing and notarization are not yet configured.

Docker

The published image supports Linux amd64 and arm64. Docker Desktop on macOS and Windows runs the same Linux image:

cp .env.example .env# Set ANTEATER_MCP_TOKEN in .env, then:docker compose up -dcurl -fsS http://127.0.0.1:8787/health

The Compose service is non-root, read-only, capability-free and bound to loopback by default. See DEPLOY.md before placing it behind public HTTPS.

Claude Desktop

Open the config file:

Add an anteater entry. The path must be absolute — Claude Desktop does not run the server from your project directory:

{  "mcpServers": {    "anteater": {      "command": "node",      "args": ["/absolute/path/to/anteater-mcp/anteater-mcp.mjs"]    }  }}

With an API key:

{  "mcpServers": {    "anteater": {      "command": "node",      "args": ["/absolute/path/to/anteater-mcp/anteater-mcp.mjs"],      "env": { "ANTEATER_API_KEY": "your-secret-key" }    }  }}

Restart Claude Desktop completely (quit, don't just close the window). You should see 20 anteater tools, and the 6 prompts appear as slash commands.

claude_desktop_config.example.json in this repo is the same thing, ready to copy.

Claude Code

claude mcp add anteater -- node /absolute/path/to/anteater-mcp/anteater-mcp.mjs

With a key:

claude mcp add anteater -e ANTEATER_API_KEY=your-secret-key -- node /absolute/path/to/anteater-mcp/anteater-mcp.mjs

Verify with claude mcp list.

ChatGPT

Two routes. The first needs no server.

node anteater-mcp.mjs --http --port 8787   # binds 127.0.0.1 only — do not add --host# in another terminalngrok http 8787      # or: cloudflared tunnel --url http://localhost:8787

https://<your-domain>/mcp?token=<ANTEATER_MCP_TOKEN>

⚠️ ChatGPT's MCP plugins are web-only. OpenAI's own documentation says developer mode is "available to Pro, Plus, Business, Enterprise, and Education accounts on the web" — the phone apps cannot reach an MCP server. For ChatGPT on a phone, use a Custom GPT whose Action points at this server's REST facade, described below.

Which ChatGPT route gets you what

On your phone

Claude's iOS and Android apps support remote MCP servers. Deploy this behind HTTPS, add it once on claude.ai in a browser, and it syncs to the apps — you cannot add a new server from the phone itself. DEPLOY.md has a complete recipe: token auth, a systemd unit, Caddy or nginx, and the connector setup.

The ChatGPT Custom GPT route also works on mobile and needs no server at all.

Codex

Codex speaks streamable HTTP and reads the token from an environment variable, so it never lands in a config file:

export ANTEATER_MCP_TOKEN=...   # in your shell profilecodex mcp add anteater --url https://your.domain/mcp --bearer-token-env-var ANTEATER_MCP_TOKEN

Or write it to ~/.codex/config.toml directly — a project-local .codex/config.toml takes precedence over the global one:

[mcp_servers.anteater]url = "https://your.domain/mcp"bearer_token_env_var = "ANTEATER_MCP_TOKEN"

Codex reads the variable at connect time and sends Authorization: Bearer <token>.

Any other MCP client

The server speaks standard MCP over stdio. Point your client at:

command: nodeargs:    ["/absolute/path/to/anteater-mcp/anteater-mcp.mjs"]

Or run it as a streamable-HTTP server at http://127.0.0.1:8787/mcp with node anteater-mcp.mjs --http.

Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05 are all accepted; the server negotiates down rather than echoing whatever it is sent.

What you get

Tools (20)

Finding classes

Judging a class before you take it

Checking you can actually enrol

Planning a degree

Five of these compute things the upstream API does not provide: prerequisite-tree evaluation, schedule conflict detection, the join between the live schedule and historical grade data, AP-grant rendering, and deterministic degree-progress evaluation.

All 20 are annotated readOnlyHint: true — nothing here mutates anything.

Prompts (6)

In Claude Desktop these appear as slash commands. Each one drives a full multi-tool workflow rather than a single lookup.

* = required. Arguments named term, ge, department, major and course offer autocomplete through the MCP completions API.

Resources (4)

Reference tables your client can read directly, without spending a tool call:

• anteater://reference/departments — every department code and name
• anteater://reference/terms — every term with schedule data
• anteater://reference/ge-categories — GE codes and what they mean
• anteater://reference/restriction-codes — enrollment restriction codes, per the Registrar

Configuration

API key

Optional, but recommended: anonymous calls draw on a shared hourly quota that is easy to exhaust, and a key gives you your own.

It will not unlock fuzzy search. /v2/rest/search rejects ordinary keys with not permitted to access this resource — it needs elevated permission ICSSC grants separately. Without it search_courses falls back to substring matching on title, then description, and says so in its output. The structured filters (department, geCategory, courseLevel, units) are unaffected and are usually the better tool anyway.

1. Go to dashboard.anteaterapi.com/create
2. Choose type secret — publishable keys are verified against the Origin header, which Node does not send, so they will not work here
3. Either set it in your client config (see above), or for local development:

cp .env.example .env     # then edit .envset -a; . ./.env; set +a # load it without echoing the value

.env is gitignored. Never paste a key into an issue, PR or screenshot.

Shared and personal upstream keys (MCPHub)

For direct execution inside MCPHub, import the stdio configuration in the MCPHub guide. Each user can bind a personal key, and a separate shared entry uses the public/default key. No independent Anteater container is required. The following header mechanism is for HTTP deployments.

HTTP calls can use either the deployment's shared ANTEATER_API_KEY or a personal key sent as X-Anteater-Api-Key. The personal header takes precedence for that request, including all of its concurrent upstream calls. If the header is absent, the shared key is used (or anonymous upstream access if no shared key is configured). A blank or ambiguous personal header is rejected; an invalid personal key never retries with the shared key. Anteater API caches are separated by credential.

Authorization: Bearer <ANTEATER_MCP_TOKEN> still authenticates access to this server. It is independent of the upstream API key and is required for both modes when configured. Personal keys belong in headers, never URL query parameters.

See MCPHub setup for separate Shared and Personal server entries. Personal entries require a binding; Shared remains available without one.

Environment variables

Command line

node anteater-mcp.mjs                    # stdio (what MCP clients use)node anteater-mcp.mjs --http             # HTTP on 127.0.0.1:8787, endpoint /mcpnode anteater-mcp.mjs --http --port 9000 # different portnode anteater-mcp.mjs --http --host 0.0.0.0  # bind all interfaces (warns; see below)node anteater-mcp.mjs --list-tools       # list every tool

HTTP mode security

• Binds 127.0.0.1 by default. server.listen(port) with no host binds every interface, which would expose an unauthenticated server to the whole LAN. --host is required to change that, and it warns when you do.
• Validates Origin. The MCP specification requires this of local HTTP servers: without it, any page you visit can POST to your port and drive every tool (DNS rebinding / CSRF). Requests with no Origin — native MCP clients — are allowed; requests with one must be localhost or listed in ANTEATER_ALLOWED_ORIGINS.
• Access-Control-Allow-Origin echoes the single validated origin, never *.
• Unauthenticated unless ANTEATER_MCP_TOKEN is set. That is fine on loopback and not fine anywhere else; the server warns at startup if it is bound off-loopback without one. See DEPLOY.md.
• HTTP activity is logged to stderr as one JSON request line and one response line. Logs include a request ID, method, sanitized target, remote address, status, duration, RPC/tool name, and outcome when available. Authorization values and RPC arguments are never logged; URL token values are shown as [REDACTED].
• /health reports status and the source URL; /source redirects to this repository, which helps anyone deploying a modified copy comply with AGPL section 13.

Errors

A failed tool call returns isError: true and a single text content item holding a JSON object, so a client can tell a bad credential from a service outage without parsing prose:

{"error": "RATE_LIMITED", "message": "Anteater API rate limit hit. Wait a moment, or set ANTEATER_API_KEY ...", "retry_after_seconds": 30}

message stays human-readable and is safe to show to a user; it never contains the API key. Codes are stable; wording is not.

The REST facade (/tools/<name>) keeps HTTP 200 with {"result": ..., "isError": true} for a tool failure. result is the same JSON string as the MCP text, and a top-level "error": "<CODE>" repeats the code. Transport problems keep their HTTP status but now share one body shape, {"error": "<CODE>", "message": "<text>"}, with error one of INVALID_ARGUMENT (400), UNAUTHORIZED (401), NOT_FOUND (unknown tool, 404), METHOD_NOT_ALLOWED (405) or PAYLOAD_TOO_LARGE (413). A failing resources/read keeps JSON-RPC error -32603 and adds data: {"error": "<CODE>"}. All of this is described in /openapi.json. The static gpt-actions-openapi.json talks to Anteater API directly and is unaffected.

Changes

1.0.0-beta.3

• Tool failures are now structured. The text content of an isError result is a JSON object {"error": CODE, "message": text} instead of Error: ... prose. Codes: CREDENTIAL_INVALID, PERMISSION_DENIED, RATE_LIMITED, INVALID_ARGUMENT, SOURCE_UNAVAILABLE.
• REST facade result format change. On failure, /tools/<name> still returns HTTP 200 with isError: true, but result is now that JSON string rather than Error: ... prose, and a top-level error code is added. Transport errors (400, 401, 404, 405, 413) now return {"error": CODE, "message": text} where some returned plain text or {"error": text}. Match on error, not on the old Error: prefix.
• New ANTEATER_API_KEY_SCOPE (operator default, or user).
• get_course, check_prerequisites no longer report an upstream outage or rate limit as "No course ...": only a real 404 does.

Troubleshooting

Development

npm test                # 20 conformance tests; makes no API callsnpm run test:live       # live calls; needs a key in practicenpm ci                  # build tooling only; the shipped server has no runtime packagesnpm run build:sea       # standalone binary; requires the exact Node in .node-version

UPSTREAM.md records the exact Anteater API version and the upstream commits this server was validated against, endpoint by endpoint — start there when the API changes and something begins returning wrong or empty results.

VERIFICATION.md is a full release checklist — per-regression pass criteria, security checks and integration checks — written so someone who has never read the code can run it.

CI uses the same pinned Node 24 LTS release as Docker and native packaging. It runs the offline suite, syntax and OpenAPI checks, a standalone-executable smoke test, and a locked-down container protocol test. It deliberately makes no live Anteater API calls, so it never draws on the public rate limit.

Pushing a tag that exactly matches v plus the package.json version builds six native executables, generates checksums and provenance attestations, pushes an amd64/arm64 image to GHCR, and publishes the GitHub Release. Stable tags update :latest; every release updates :beta; exact :vX.Y.Z tags are immutable.

After the first image publish, set the GHCR package visibility to Public once. The workflow uses the scoped GITHUB_TOKEN; if repository policy blocks bot-created Releases, add a fine-grained RELEASE_PAT secret with Contents write access, matching the upstream project's fallback.

Scope

Anteater API also serves dining halls, library traffic and study-room bookings. Those are deliberately not wrapped — this server stays focused on choosing and registering for classes.

LARC tutoring sections are in scope but effectively dead upstream: /v2/rest/larc returns 22 courses for 2024 Fall and nothing for any term since, so a tool would always answer "none" for the term a student is actually planning.

Known limitations

These are properties of the upstream data, not bugs. The server states them rather than papering over them, because the alternative is confident wrong advice.

• WebSoc does not publish which discussion belongs to which lecture. Some courses encode it in the section number (Lec A → Dis A1), others number companions independently (I&C SCI 31: lectures A/B, labs 1–9). check_schedule therefore tells you when a required component is missing entirely, and when a pairing cannot be verified — but it cannot confirm that a given lab goes with a given lecture. Confirm that on WebReg. Neither of ICSSC's own clients infers this either: AntAlmanac and PeterPortal both render sections as a flat list and leave the pairing to the student, which is good evidence the data simply is not there.
• Enrollment restrictions are not evaluated against you. search_sections and recommend_courses surface the codes and their meanings; whether you satisfy "Major only" or "Graduate only" is enforced by the registrar.
• Transfer and community-college coursework is absent. check_prerequisites reports any completed course it does not recognise instead of silently ignoring it, but only an advisor can clear transfer credit.
• No registration-window dates. The academic calendar covers instruction and finals; it does not say when your enrollment window opens. Check StudentAccess.
• Grade data lags. Recent quarters may be missing, and a recent term's grades are often filed under STAFF. A small sample size makes an average GPA unreliable — the tools always print n so you can judge.
• Historical GPA is course-wide. recommend_courses ranks by the average across all past instructors, which may not be whoever is teaching this term. Use get_course_grades to check the specific instructor before deciding.

Bugs found and fixed before release

A six-dimension parallel review (logic, MCP conformance, live-API contract, security, robustness, repo readiness) produced 41 raw findings, 38 after deduplication. The ones that would actually have misled someone:

A second round, driving the server through six realistic student scenarios end to end, found 54 more — 10 of them blockers. The worst:

Also fixed: inverted check marks in NOT prerequisite subtrees, course numbers lost for the 48 department codes containing a space, multi-byte UTF-8 corrupted across HTTP chunk boundaries, a quadratic-backtracking regex on unvalidated input, and socAvailable mislabelled as "enrollment opens" when it is the schedule publication date.

API quirks worth knowing

Undocumented upstream; all handled here, and listed in case they save you the debugging.

• days must be comma-separated. Tu,Th works, TuTh is rejected. It matches at least one of the listed days, not all of them.
• enrollmentHistory returns parallel arrays (dates[], totalEnrolledHistory[], requestedHistory[], …), not scalars. -1 means "not tracked".
• finalExam.month is 0-indexed.
• Course comments are raw HTML fragments, complete with <p> and ".
• startTime / endTime mean "starts at or after" and "ends at or before", not interval overlap.
• /v2/rest/search needs a privileged API key. An ordinary key is refused with not permitted to access this resource, which is a different error from the key is required you get with no key at all — worth distinguishing, since telling someone who already has a key to get a key is a dead end.
• /v2/rest/websoc/syllabi takes courseId, not department + courseNumber.
• /v2/rest/courseMaterials needs department AND courseNumber together. Either alone is refused, and it collapses the three summer sessions into a single Summer.
• Restriction strings contain prose. "A and N" must be split on whitespace and have the literal and/or discarded, or the conjunction renders as a code.
• Section status is an enum, not free text: OPEN, Waitl, FULL, NewOnly, or empty. Only OPEN means a continuing student can enrol now — NewOnly marks seats held for incoming students. numNewOnlyReserved counts seats inside the capacity that are reserved the same way, so the apparent opening overstates the real one.

Distribution

Published to the MCP Registry as io.github.KKazuhaK/anteater-mcp, listing the container image only. The registry entry describes how to run your own instance; it does not point at anyone's deployment, since a hosted instance is gated behind its own token and its upstream quota belongs to whoever runs it.

Each release also publishes the GHCR image and standalone binaries for six platforms.

Licence and attribution

Data from Anteater API, maintained by ICSSC Projects.

This is not an official UCI tool. Verify on WebReg or the General Catalogue before registering. Use is subject to Anteater API's attribution policy.

Licensed AGPL-3.0-or-later, matching the upstream Anteater API server so code can move freely in either direction if this is ever contributed upstream. This is an independent HTTP client and contains no upstream source code. If you modify it and run it as a network service, AGPL section 13 requires you to offer users your Corresponding Source — see NOTICE.

For academic use:

@misc{anteater-api,  author = {ICS Student Council},  title = {Anteater API},  year = {2024},  howpublished = {\url{https://github.com/icssc/anteater-api}},}