Anteater-MCP

# Anteater MCP

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

It wraps [Anteater API](https://icssc.link/about-anteaterapi) — 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 134
UNI STU H30A  ANALYSIS HEALTH LIT  4      3.77  84%  864   15         TuTh 12:30-13:50 @ ALP 1600
LPS 31        INTRO INDUCT LOGIC   4      3.61  80%  2108  11         TuTh 14:00-15:20 @ EH 1200
```

---

## Quickstart

```bash
git clone https://github.com/KKazuhaK/Anteater-MCP.git
cd anteater-mcp
node --version                         # Node 24 LTS
node anteater-mcp.mjs --list-tools     # confirm it runs
```

Then add it to your client — **[Claude Desktop](#claude-desktop)**,
**[Claude Code](#claude-code)**, **[ChatGPT](#chatgpt)**, or
**[any other MCP client](#any-other-mcp-client)**.

Nothing else is required. An [API key](#api-key) is optional but recommended.

---

## Installing

### Standalone binary

Each [GitHub Release](https://github.com/KKazuhaK/Anteater-MCP/releases) contains native
archives for Linux, macOS and Windows on amd64 and arm64, plus `SHA256SUMS.txt`. These do
not require Node.js:

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

```bash
cp .env.example .env
# Set ANTEATER_MCP_TOKEN in .env, then:
docker compose up -d
curl -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](DEPLOY.md) before placing it behind public HTTPS.

### Claude Desktop

Open the config file:

| OS | Path |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

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

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

With an API key:

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

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

With a key:

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

<details open><summary><b>A. Custom GPT with Actions — no hosting required</b></summary>

1. ChatGPT → **Explore GPTs → Create → Configure → Create new action**
2. Paste the contents of [`gpt-actions-openapi.json`](gpt-actions-openapi.json) into the
   Schema box
3. **Authentication** — two workable choices:
   - **None.** Anteater API is readable anonymously. Simplest, but you share a global
     hourly quota with every other anonymous caller and will hit 429s.
   - **API Key → Auth Type: Bearer**, with your Anteater API key. ChatGPT then sends
     `Authorization: Bearer <key>` on every call and you get your own quota. ⚠️ The key is
     stored with the GPT, so **anyone you share the GPT with uses your key**. Fine for a
     private GPT; do not publish one with your key in it.
4. Paste [`gpt-instructions.md`](gpt-instructions.md) into the Instructions box

The GPT calls `anteaterapi.com` directly. Twelve operations cover courses, WebSoc,
grades, enrollment history and degree requirements.

**The trade-off:** the GPT receives raw JSON. WebSoc responses nest four levels deep
(`schools > departments > courses > sections`), so broad queries get truncated by
Actions — the supplied instructions tell it to always narrow. Prerequisite evaluation
and conflict detection are *not* available; the model has to reason them out itself.
</details>

<details><summary><b>B. Host the MCP server — full functionality</b></summary>

ChatGPT's Developer Mode connector needs a public HTTPS MCP endpoint:

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

Add the URL under **Settings → Connectors → Advanced → Developer mode**. All 20 tools
work, including batch course lookup, deterministic degree-progress checks, prerequisite
checking and conflict detection.

ChatGPT's developer mode supports **OAuth, no authentication, or mixed** — there is no
field for a custom header, so put the token in the URL query string:

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

This URL form is a compatibility option, not a security improvement: URLs may be saved
in connector settings and reverse-proxy logs. Use a Bearer header whenever the client
supports one.

Both transports ChatGPT accepts, SSE and streaming HTTP, are implemented. For a permanent
deployment rather than a tunnel, follow [DEPLOY.md](DEPLOY.md) — the setup is identical to
the Claude one, only the connector UI differs.

> ⚠️ Without `ANTEATER_MCP_TOKEN` the endpoint is unauthenticated. Set it before exposing
> anything. See [HTTP mode security](#http-mode-security).
</details>

> ⚠️ **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

| | Custom GPT + Actions | Developer mode + MCP |
|---|---|---|
| Server needed | No | Yes, public HTTPS |
| Auth options | None · API Key (Basic/Bearer/**custom header**) · OAuth | Access token / API key with a **Bearer, Basic or custom header** scheme · OAuth · none. Claude's connector dialog takes request headers too, so `?token=` is only a fallback |
| Can carry your Anteater key | Yes, API Key → Bearer | Yes, server-side via `ANTEATER_API_KEY` |
| What the model gets | 12 raw API operations, JSON | All 20 tools, formatted, plus 6 prompts and 4 resources |
| Prerequisite / conflict checking | No — the model must reason it out | Yes |
| Works on mobile | Yes | **No** — MCP plugins are web-only |

### 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](DEPLOY.md) has a complete recipe: token auth,
a systemd unit, Caddy or nginx, and the connector setup.

The [ChatGPT Custom GPT route](#chatgpt) 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:

```bash
export ANTEATER_MCP_TOKEN=...   # in your shell profile
codex 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:

```toml
[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: node
args:    ["/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**

| Tool | What it answers |
|---|---|
| `search_sections` | **The workhorse.** Live sections for a term: times, instructor, room, seats, waitlist, final exam. Supports an *exclusive* day filter (`daysOnly`) and a blocked-window filter (`avoidDays` + `avoidStart`/`avoidEnd`) for "I work Monday afternoons" |
| `recommend_courses` | **The one you want.** Filter by GE, days, time window and open seats; rank by historical GPA |
| `search_courses` | What courses exist at all |
| `get_course` | One course in full: description, prerequisites, restrictions, what it