# opentable-mcp

MCP server for OpenTable restaurant search and availability, reverse-engineered from observed web traffic.

Built entirely by Claude Opus 4.8 via Claude Code.

## Overview

Exposes anonymous, read-only OpenTable restaurant discovery and availability through MCP tools. It can find restaurants and check tables — it cannot book.

- `opentable_autocomplete` — resolve a place, cuisine, or restaurant name to search anchors (restaurantId, lat/long, metroId, areaId)
- `opentable_list_regions` — metro and sub-region geography with ids and restaurant counts
- `opentable_nearby_restaurants` — restaurants near a lat/long with name, restaurantId, cuisine, price band, rating, phone, and profile URL
- `opentable_restaurant_availability` — bookable time slots for one or more restaurants on a single date, time, and party size
- `opentable_multi_day_availability` — a single restaurant's availability scanned forward across many days
- `opentable_session_status` — inspect or force-refresh the session and Akamai cookie state

Typical workflow: `opentable_autocomplete` resolves a name to a `restaurantId`, then `opentable_restaurant_availability` or `opentable_multi_day_availability` checks tables. Availability slots are raw data — each `dateTime` is ISO-8601 local to the restaurant (no timezone), plus the raw `timeOffsetMinutes`.

## Setup

```bash
npm install
npm run build
npm run verify
```

No configuration is required — the server mints its own session on first use. Copy `.env.example` to `.env` for optional overrides (default search center, captured-cookie fallback, browser settings).

Requires Node.js 20+ and Google Chrome installed (used via `playwright-core` to mint an Akamai-valid session; no separate browser download). No OpenTable account needed.

## MCP Setup

The server runs over stdio. Example client configuration:

```json
{
  "mcpServers": {
    "opentable": {
      "command": "node",
      "args": ["/absolute/path/to/opentable-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/opentable-mcp"
    }
  }
}
```

For local development, use `npx tsx src/index.ts` instead of the built output. A `manifest.json` is included for bundle-aware clients.

## Notes

- Anonymous and read-only — no account, no booking. The booking flow is intentionally out of scope.
- OpenTable is behind Akamai Bot Manager, whose `_abck` cookie is only validated by a real browser. The server mints a session lazily with a headful (offscreen) Chrome via your installed Chrome, persists it to `~/.config/opentable-mcp/session.json`, and re-mints only when a request is blocked — no scheduler. A captured `OPENTABLE_COOKIE` is used as a fallback when present.
- Minting launches Chrome with `--disable-blink-features=AutomationControlled` (required for the availability endpoint to trust the session), which shows a cosmetic "unsupported command-line flag" banner.
- Heavy back-to-back use can trip Akamai IP rate-limiting; it recovers after a short cooldown.
- Tool errors carry a machine-readable `code` (`AKAMAI_BLOCKED`, `PERSISTED_QUERY_NOT_FOUND`, `CSRF_REJECTED`, `SESSION_UNAVAILABLE`). See `docs/api-spec.md` for the reverse-engineering notes.