# grubhub-mcp

an mcp server for grubhub. it can search restaurants, browse menus, build carts,
inspect checkout state, attach payment, and place orders.

this also has campus dining helpers for usc/carolinacard. it can pull the
same campus-card balances the grubhub mobile app shows, including meals, retail
meals, meal plan dollars, and carolina cash when grubhub returns them.

python 3.11+ is required. dependencies: `mcp`, `httpx`, `pydantic`

## setup

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
python -m grubhub_mcp
```

on windows:

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .
python -m grubhub_mcp
```

by default the server runs over stdio, which is what most local mcp clients want.

```json
{
  "mcpServers": {
    "grubhub": {
      "command": "/path/to/grubhub-mcp/.venv/bin/python",
      "args": ["-m", "grubhub_mcp"]
    }
  }
}
```

## env vars

```text
MCP_TRANSPORT=stdio | http | streamable-http | sse
HOST=127.0.0.1
PORT=8001
MCP_PATH=/mcp
MCP_ALLOWED_HOSTS=comma,separated,hosts
MCP_ALLOWED_ORIGINS=comma,separated,origins
MCP_JSON_RESPONSE=1
GRUBHUB_SESSION_DIR=~/.grubhub-mcp
GRUBHUB_USER_AGENT="Grubhub/2026.24.2 (Android; Android 15)"
```

`GRUBHUB_SESSION_DIR` is where login state is stored. keep that directory private.
the session file contains grubhub auth tokens.


## undocumented endpoints (yay genymotion!)

this talks to grubhub's private/mobile api. some endpoints were mapped from the
android app, including the campus-card balance call:

```text
/tapingo/payments/{diner_udid}/campus-cards/v2/cards-balances
```

reverse engineering is EPIC!