Dine MCP

dine-mcp

Restaurant table availability across the booking systems restaurants actually use, in any country, for AI assistants (MCP), the command line and Python.

Ask "can we get a table for four at Harbour Grill on Friday evening?" and the assistant finds the venue, works out which booking system it uses (from Google Maps' "Reserve a table" link, the venue's booking page, or curated facts), checks the open times in the venue's own time zone, and gives you the provider's booking page, prefilled where it can be. dine-mcp never books, holds or cancels anything: you book yourself, on the provider's page.

SevenRooms returns bookable/request slots, experiences and card flags; ResDiary includes seating areas. TableCheck does not publish its release window, so unreleased dates can look full. Other booking pages are link-only; phone, messaging and website-only venues return contact details. Optional website discovery can detect a supported widget when the place listing has no booking link.

More providers come as definitions and adapters (CONTRIBUTING.md); what is next is in docs/ROADMAP.md.

Unofficial. Not affiliated with any booking provider or with Google. The providers' terms restrict automated access: dine-mcp reads only their public booking widgets, for a person checking a table for themselves, at human pace, and never books. Use it for personal, low-volume purposes, at your own risk. Venue lookups use Google Maps through google-maps-keyless-mcp, whose terms note applies too.

Quick start

Release: 0.2.10. See the changelog for its security update and availability fixes. From a source checkout, run:

uv sync --lockeduv run dine-mcp --transport stdio

The equivalent package command and client configurations are:

uvx dine-mcp --transport stdio            # for a local MCP client (Claude Desktop, Claude Code, …)

Claude Code: claude mcp add dine -- uvx dine-mcp --transport stdio. Claude Desktop (claude_desktop_config.json):

{"mcpServers": {"dine": {"command": "uvx", "args": ["dine-mcp", "--transport", "stdio"]}}}

The command line does the same without an assistant:

uvx dine-mcp find "Harbour Grill" --area "Raffles Place" --country SGuvx dine-mcp check v_abc123def456 --date 2026-11-06 --from-time 18:00 --to-time 21:30 --party 4

Tools

All tools are read-only. Every result also comes as short text for clients that show only text.

To check a restaurant, resolve it with dine_find_venue, then call dine_check_availability. Ask for missing dates and diner count first, and state the time window used (the API defaults to 17:00–22:30). dine_status diagnoses the service; it does not check a restaurant's tables. Failed requests and unchecked dates mean unknown availability, never evidence that it is sold out.

Statuses (per venue and channel): ok, none_available, not_yet_open (the dates are not released yet; opens_at when known), party_too_small (with min_party) or party_too_large (with the venue's online maximum and its contact), closed, contact_only, unsupported (a booking system dine-mcp does not read; the link is given), blocked / rate_limited (the provider asked us to slow down), unavailable, unknown_venue, skipped_deadline. One provider failing never fails the call.

Limits: at most 5 venues and 7 days per availability call. Plans estimated above 20 provider requests are refused with too_broad; actual dispatches, including redirects, share the same cap. Find, get and check share a 30-second end-to-end deadline across lookup, planning and provider work. Completed batches survive later errors and deadlines; omitted dates remain unknown, never evidence of no availability. Observations are cached for two minutes. TableCheck reuse requires the same time window; older observations returned during pushback are labelled with their original time. Progress notifications are supported over stdio; stateless JSON HTTP returns the completed result.

Errors are tool results with isError whose text is {"error": {"code", "retryable", "retry_after_seconds", "action", "next_step"}}.

Running a server

A hardened Compose example provides a read-only root, dropped capabilities and a private state volume. Set DINE_IMAGE to a verified immutable image digest for deployment. Configure the HTTP Host/Origin allowlists for your proxy before accepting remote clients.

Run uv run dine-mcp --transport http from a source checkout, or set DINE_IMAGE to the verified immutable digest of the 0.2.10 image before starting the container:

docker run -d -p 127.0.0.1:8000:8000 -v dine-state:/state \  -e MCP_BEARER_TOKEN="$(openssl rand -hex 32)" \  "${DINE_IMAGE:?set a verified immutable image digest}"

The MCP endpoint is /mcp (streamable HTTP, stateless JSON); /health is open. Who is calling decides which share of the request budget is used:

Overrides (DINE_OVERRIDES, TOML) are the operator's only switch, applied at start-up:

disabled = false                 # true: find/get/check refuse before external work[providers.tablecheck]access_mode = "listing"          # stop reading availability; return links only (never raise a mode)[providers.sevenrooms]enabled = false                  # off entirely

Each provider is paced to one request every two seconds, one at a time, within a daily budget shared by everyone on the server (each person may use half of it), and pauses for at least five minutes when it pushes back (429, 401 or 403, or a bot check). It never retries or solves a challenge.

When website discovery is enabled, find/get/check may read the current place-source website if no booking channel is known. It recognizes supported anchors and iframe/button attributes without JavaScript or crawling. Multiple distinct venue widgets are ambiguous and produce no inferred channel. Detected links are provisional (source=website, verified=false), cached for at most a day and never beyond the place-source record; they do not create permanent venue aliases.

Booking-provider hosts stay behind their adapters; website discovery cannot bypass their pinned operations or budgets. A source website already naming a supported booking venue is recognized without fetching it. Website reads use a separate credential-free client, a 512 kB decoded-body cap and a five-second optional-enrichment deadline. HTTPS, public DNS and exact-host redirects are enforced. All sites share 50 reads per day, half per person, paced one second apart; redirects count too. Failed reads back off for 15 minutes, and refusals share a persistent pause. Directory results survive discovery failure. dine_status reports the feature's aggregate budget and pause without reading websites. Disable it and restart to remove cached discovery data. Website requests omit tracking parameters and fragments; source URLs with other queries and redirects carrying queries are refused. Discovery stores only query-free recognized booking links, with no raw HTML or cookies. Original place data follows its usual retention policy.

Authentication, operator actions, revocation and shared data are documented in docs/PERMISSIONS.md.

Use as a library

from dine_mcp.composition import build_app
app = build_app()found = await app.service.find_venue("me", name="Harbour Grill", area="Raffles Place", country="SG")venue_id = found["venues"][0]["venue_id"]result = await app.service.check_availability("me", [venue_id], "2026-11-06", party_size=4)

The tool surface follows SemVer; the Python API is not yet stable (0.x).

How it works

docs/ARCHITECTURE.md explains venue resolution, the provider protocol, the request budget and the safety boundary; docs/PROVIDERS.md lists each provider's endpoints, limits and quirks; docs/ROADMAP.md what comes next.

Verification

make check runs offline safety, contract, real stdio/HTTP, isolation and regression checks. make qualify additionally installs pinned Node 22+ tools and runs Inspector plus the applicable generic MCP conformance scenarios. See verification for scope, package checks and the separately gated operator canaries. Health checks never contact providers.

Licence

Apache-2.0. Prior art and dependencies are credited in NOTICE.

Optional availability grid

Set DINE_APPS=1 to advertise ui://dine/availability.html to MCP Apps hosts. The bundled view shows venues against venue-local service dates, including after-midnight slots, observation timestamps and unknown coverage. Filters run locally. Booking-page navigation asks the host to open an HTTPS link only after a click; the view never calls providers or tools itself. Clients without Apps continue to receive the text and structured result. The option defaults off.

Development needs Node 22+ for make ui (rebuild) and make ui-check (locked dependencies, reproducible bundle/notices and offline rendering/SDK tests). Python installations need no Node. See roadmap for the remaining provider and connection prerequisites.

The generated interface reference records complete MCP discovery (including the optional App profile) and CLI parser declarations. Run python scripts/surface.py update after a deliberate interface change and review surface.json with the reference diff. make check refuses missing or stale baselines. Environment and configuration coverage is explicitly partial while those declarations remain distributed across the loaders; this reference does not replace the configuration guidance above. Image smoke compares the installed entry point's complete discovery schemas and synthetic success/error behavior.