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.

Provider	Countries	Mode	Maturity	Last verified live
CatchTable (Korea)	KR	listing	experimental	unverified
Formitable (Zenchef)	NL, BE, FR, DE, GB	public	experimental	unverified
ResDiary	GB, IE, AU, NZ, AE, SG, HK, MY, ZA	public	beta	2026-10-29
SevenRooms	HK, GB, US, AE, AU, SG, IE, CA	public	beta	2026-10-29
Tabelog	JP	listing	experimental	unverified
TableCheck	JP, HK, SG, KR, TW, TH, AU, GB, US	public	beta	2026-10-29
Zenchef	FR, NL, BE, GB, DE, CH, ES, IT	public	experimental	unverified

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.3. From a source checkout, run:

uv sync --locked
uv 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 SG
uvx dine-mcp check v_abc123def456 --date 2026-11-06 --from-time 18:00 --to-time 21:30 --party 4

Tools

Tool	What it does
dine_find_venue(name, area, country | url | google_place_id, limit)	Identifies one restaurant and its booking channels. Ambiguous names return candidates with their Google place ids, never a guess. A booking link is only matched against known providers, never fetched.
dine_get_venue(venue_id)	The venue in full: each provider's booking rules (days ahead, party size limits), booking links, opening hours.
dine_check_availability(venue_ids ≤5, date_from, date_to ≤7 days, time_from, time_to, party_size, kinds, response_format)	One result per venue and channel: slots in the venue's time zone, coverage, observed_at, the booking link.
dine_status(check=false)	Providers, budgets and pauses. Optional paced canaries share a durable 15-minute cooldown.

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

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 locally built image until the first image is published. Configure the HTTP Host/Origin allowlists for your proxy before accepting remote clients.

Before an image is published, use uv run dine-mcp --transport http from the source checkout with the environment below. After the first image release:

docker run -d -p 127.0.0.1:8000:8000 -v dine-state:/state \
  -e MCP_BEARER_TOKEN="$(openssl rand -hex 32)" ghcr.io/benjamin-di/dine-mcp-server:latest

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

Mode	Set	Person
single	MCP_BEARER_TOKEN	one person, owner
users (standalone multi-user)	DINE_USERS_FILE; dine-mcp users add <id> --file users.toml prints that user's token once	the user whose token was presented
gateway	MCP_BEARER_TOKEN (the gateway's) and DINE_PERSON_HEADER (e.g. X-Person)	the validated person the authenticating gateway asserts; a record is created on first contact
stdio	--transport stdio	the local user

Variable	Default	Meaning
DINE_STATE_DIR	$XDG_STATE_HOME/dine-mcp (/state in the image)	venues, budgets, breakers, the roster
DINE_OVERRIDES	none	operator switches (below)
DINE_PLACES	google	none turns off venue search by name (links still work)
DINE_GOOGLE_DAILY_BUDGET	200	Google Maps requests per day
DINE_WEBSITE_DISCOVERY	0	1 enables bounded HTML discovery on the venue website supplied by the place source
DINE_DEADLINE_SECONDS	30	end-to-end timeout for find/get/check and explicit canaries
DINE_HTTP_ALLOWED_HOSTS	localhost,127.0.0.1,[::1]	explicit HTTP Host allowlist; add your reverse proxy hostname
DINE_HTTP_ALLOWED_ORIGINS	empty	comma-separated exact cross-origin HTTP origins; same-origin is accepted
DINE_APPS	0	Set to 1 for the optional MCP Apps availability grid; text results remain available
DINE_HOST, DINE_PORT	127.0.0.1, 8000	HTTP listen address

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.