opentable-mcp

# opentable-mcp

[![CI](https://github.com/chrischall/opentable-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/chrischall/opentable-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/opentable-mcp)](https://www.npmjs.com/package/opentable-mcp)
[![license](https://img.shields.io/npm/l/opentable-mcp)](LICENSE)

OpenTable reservation manager as an MCP server for Claude — find slots, book, cancel, manage favorites, and read your dashboard via natural language.

> **v0.3.0-alpha status: Chrome-extension bridge, 10 tools, read + write.** Every OpenTable request is relayed through your signed-in Chrome tab over a localhost WebSocket — each request rides your existing session and reaches OpenTable as if you'd clicked it yourself.

## How it works

OpenTable's edge (Akamai Bot Manager) enforces a behavioral challenge on `/`, `/s`, `/r/…`, `/dapi/…`, and `/booking/…`. Tooling that builds its own HTTP client — cycletls, impersonated curl, headless Chrome — invents a separate identity and gets a 403 or JS interstitial. opentable-mcp does the opposite: it uses your own browser session as-is, with the cookies and TLS context it already has.

So instead of standing in for the browser, this MCP server:

1. Starts a WebSocket listener on `127.0.0.1:37149` via [`@fetchproxy/server`](https://github.com/chrischall/fetchproxy).
2. The [fetchproxy browser extension](https://github.com/chrischall/fetchproxy) (installed once, shared across all fetchproxy-based MCPs) connects from your signed-in browser and relays every request through the opentable.com tab via `fetch(..., { credentials: 'include' })` — your TLS, your cookies, your already-solved `_abck`.
3. Parses JSON responses (public GraphQL / JSON endpoints) and SSR HTML (`/user/*`) into tool-shaped output.

No cookie-pasting. No cycletls. No Playwright. Just your own browser, acting on its own behalf — the MCP server only picks what to ask for.

## Tools

| Tool | Kind | Source |
| --- | --- | --- |
| `opentable_list_reservations` | read | `/user/dining-dashboard` SSR |
| `opentable_get_profile` | read | `/user/dining-dashboard` SSR |
| `opentable_list_favorites` | read | `/user/favorites` SSR |
| `opentable_search_restaurants` | read | `/dapi/fe/gql?opname=Autocomplete` |
| `opentable_get_restaurant` | read | `/r/{slug}` SSR (`__INITIAL_STATE__`) |
| `opentable_find_slots` | read | `/dapi/fe/gql?opname=RestaurantsAvailability` |
| `opentable_book` | write | `SlotLock` → `/dapi/booking/make-reservation` |
| `opentable_cancel` | write | `/dapi/fe/gql?opname=CancelReservation` |
| `opentable_add_favorite` | write | `/dapi/wishlist/add` |
| `opentable_remove_favorite` | write | `/dapi/wishlist/remove` |

## Acknowledgement of Terms

By using this MCP server, you acknowledge and agree to the following:

**1. This server accesses your own OpenTable account.** Every request is dispatched through your own signed-in browser tab via the fetchproxy extension (or hangwin/mcp-chrome). It does not — and cannot — access anyone else's reservations.

**2. [OpenTable's Terms of Use](https://www.opentable.com/c/legal/terms-and-conditions/) govern your use of this server**, just as they govern your direct use of opentable.com. The clauses most relevant here:

> You may not use any deep-link, robot, spider, scraper, generative AI or other AI technology including, but not limited to, those that operate by interacting with or otherwise making use of your browser, such as automated assistants or other automatic or manual device, process, or means to access, copy, search, or monitor any portion of the Services or OpenTable Content, except as expressly authorized by OpenTable.

And, critically: *"Actions of AI agents are acknowledged as actions of the User that is using them, and the User is responsible for checking and verifying the action…"*

You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server. OpenTable's ToU explicitly enumerates AI/automated-assistant access among the things they have not authorized; they also explicitly impute AI-agent actions back to you.

**3. Personal, non-commercial use only.** This project is not affiliated with, endorsed by, sponsored by, or in partnership with OpenTable, Inc. It is a personal automation tool that drives the same `/dapi/...` and `/booking/...` endpoints opentable.com uses. Do not use it to mass-book, sweep CC-required tables, resell reservations, or for any commercial purpose. The book/cancel/modify tools exist so you can manage one reservation as if you were sitting at your browser.

**4. Stability is not guaranteed.** This server depends on internal OpenTable persisted-GraphQL query hashes that OpenTable rotates between deployments. When they rotate, tools break and we re-capture them. Your own use is at the mercy of OpenTable's release cadence.

**5. You accept full responsibility** for any consequences of using this server in connection with your OpenTable account — rate limiting, slot-lock rejections, no-show penalties for runaway bookings, account warnings, suspension, or any enforcement action. **Per OpenTable's ToU, the AI agent's actions are your actions** — review every book/cancel before you confirm. If OpenTable objects to your use, stop using this server.

This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede OpenTable's actual ToU.

## Install

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

### Install the fetchproxy extension

opentable-mcp shares one browser extension with every other fetchproxy-based MCP. Install it once from https://github.com/chrischall/fetchproxy:

1. Install the fetchproxy extension (Chrome Web Store / Safari `.dmg`).
2. Sign in to `https://www.opentable.com/` in that same browser profile.
3. The extension badge shows a green dot when the WebSocket + tab + auth cookie are all detected.

After that, any MCP client that launches `node dist/bundle.js` will reach OpenTable through your signed-in tab.

**Full setup + troubleshooting guide:** see the fetchproxy repo for the status-dot reference, WS protocol, and request lifecycle. Persisted-query hash capture for OpenTable redeploys is documented in [`CLAUDE.md`](CLAUDE.md) here.

## Configure (Claude Desktop / Claude Code)

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

No env vars required by default — auth lives in the browser, not the MCP process.

### Optional: bridge through hangwin/mcp-chrome instead

If you've installed [hangwin/mcp-chrome](https://github.com/hangwin/mcp-chrome) for browser automation, opentable-mcp can route its OpenTable fetches through it instead of the fetchproxy extension:

```json
{
  "mcpServers": {
    "opentable": {
      "command": "node",
      "args": ["/absolute/path/to/opentable-mcp/dist/bundle.js"],
      "env": { "OT_BRIDGE": "mcp-chrome" }
    }
  }
}
```

In that mode you don't need the fetchproxy extension. Every OpenTable request becomes a `chrome_network_request` call against your existing mcp-chrome install, pinned via `tabUrl` to an opentable.com tab.

**Note:** this path requires mcp-chrome ≥ the release containing [PR #348](https://github.com/hangwin/mcp-chrome/pull/348) (`tabUrl` parameter on `chrome_network_request`). Pre-#348 mcp-chrome versions are active-tab-only and will misbehave for cross-origin fetches. Live-verification of this path is pending the upstream merge.

Other env vars: `OT_WS_PORT` (default 37149) overrides the fetchproxy WebSocket port; `OT_MCP_CHROME_URL` (default `http://127.0.0.1:12306/mcp`) overrides the mcp-chrome endpoint.

## Run (local stdio)

```bash
node dist/bundle.js
```

## Test

```bash
npm test                              # vitest, 72 unit tests, mocked fetch
npm run build                         # tsc + esbuild bundle
npx tsx scripts/probe-find-slots.ts   # live GET round-trip via extension
npx tsx scripts/probe-list-res.ts     # live dashboard SSR
```

The `scripts/probe-*.ts` files spin up the MCP server, call one or two tools through the extension bridge, and print the response. They require the extension to be loaded and an opentable tab to be open.

## Troubleshooting

- **Red dot in popup / "extension offline" errors.** See the fetchproxy extension's troubleshooting guide — most "extension offline" issues are upstream lifecycle bugs (service-worker sleep, dead content script), not opentable-mcp.
- **Behavioral challenge page in Chrome.** Akamai sometimes interrupts a long-idle tab with a "verify you're human" interstitial. Click through it once and the tab is usable again.
- **`list_favorites` doesn't reflect a fresh `add_favorite`.** The `/user/favorites` SSR page is cached for a few seconds. Re-list after ~10 s or verify via `opentable_get_profile`'s count.

## Layout

- `src/transport-fetchproxy.ts` — `FetchproxyTransport`: thin adapter over `@fetchproxy/server`'s `FetchproxyServer`, the shared WebSocket bridge that talks to the fetchproxy browser extension.
- `src/client.ts` — `OpenTableClient`: wraps the transport with `fetchJson` / `fetchHtml` + error-mapping.
- `src/tools/*.ts` — one file per concern (reservations / restaurants / favorites / user / search). Each exports `registerXxxTools(server, client)`.
- `src/parse-*.ts` — pure HTML/JSON parsers, fully unit-tested.
- `tests/` — 1:1 mirror of `src/`, vitest. WS-protocol-level tests live upstream in the fetchproxy repo.
- `scripts/probe-*.ts` — live round-trip probes (require the fetchproxy extension + sign-in).

## Known quirks

- **Apollo persisted queries.** Slot search, slot lock, cancel, autocomplete — all use `extensions.persistedQuery.sha256Hash` with hashes captured from opentable.com. If OpenTable re-deploys, the server returns `PersistedQueryNotFound`; see `CLAUDE.md` → "Hot spots" for the re-capture procedure.
- **`dining_area_id` is a required book arg.** `/r