Maître d'MCP

An MCP-based that provides a set of tools to discover restaurants, checks availability, and books reservations through natural conversation with chat agents that integrate with MCP.

Note: Three MCP servers for Resy reservations already exist in the ecosystem (see Prior Art), but none combine Google Places discovery, weather integration, dining companion tracking, and real booking across both Resy and OpenTable — that gap is this project's value proposition.

What It Does

You: "Book me a quiet Italian place near home for Saturday at 7"

Claude: I found 3 Italian spots within 10 min walk of your home:
        1. Carbone (4.7★) - 6:30 PM, 9:15 PM on Resy
        2. L'Artusi (4.5★) - 7:00 PM on OpenTable
        3. Via Carota (4.6★) - 8:45 PM on Resy

        Your wife has a peanut allergy - I've verified these don't
        have nut-heavy menus. Which would you like?

You: "L'Artusi at 6:30"

Claude: ✓ Booked! Carbone, Saturday 6:30 PM, 2 people
        Confirmation: RESY-ABC123
        Add to Google Calendar: https://calendar.google.com/calendar/render?...

Key Features

Quick Start

1. Prerequisites

• Python 3.11+

• Claude Desktop installed

• Google Cloud API key (Places API enabled)

2. Clone & Install

git clone <repo>
cd restaurant-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
playwright install chromium

3. Run Setup

The interactive setup encrypts all secrets into the local database and generates your Claude Desktop config:

source .venv/bin/activate
python -m src.setup

You will be prompted for:

• Google API Key (required) — Google Cloud Console → Places API (New)

• OpenWeather API Key (optional) — openweathermap.org (free tier: 1000/day)

• Resy credentials (optional) — for automated Resy booking

• OpenTable session (optional) — CSRF token + browser cookies for OpenTable booking

The script outputs a ready-to-paste Claude Desktop config with a single RESTAURANT_MCP_KEY env var.

OpenTable's API requires authenticated browser session cookies to bypass bot protection. Without this step, OpenTable availability checks and bookings will fail.

During python -m src.setup, when you provide an OpenTable email you'll be prompted for:

• OpenTable x-csrf-token — from browser DevTools

• OpenTable Cookie header — from browser DevTools

How to get these values (re-run setup when cookies expire, typically every few days):

1. Open https://www.opentable.com in Chrome and log in

2. Open DevTools (Cmd+Option+I on macOS, F12 on Windows)

3. Go to the Network tab

4. Navigate to any restaurant page (e.g. search for "Carbone" and click it)

5. In the Network list, click any request to www.opentable.com

6. Find any request to a /dapi/ endpoint (POST) and copy the x-csrf-token header value

7. In the Headers tab, copy the full Cookie header value

8. Save the cookie value into a temp file that can be referenced in the src.setup command. This is due to the paste size being too large.

Why is this needed? OpenTable uses Cloudflare bot protection that blocks plain HTTP requests. By storing your browser's session cookies, the MCP server can make API calls as your authenticated session. The cookies are encrypted at rest using the same Fernet encryption as all other credentials.

4. Configure Claude Desktop

Copy the JSON output from step 3 into your Claude Desktop MCP config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

The config should look like:

{
  "mcpServers": {
    "restaurant": {
      "command": "/path/to/restaurant-mcp/.venv/bin/python",
      "args": ["-m", "src"],
      "cwd": "/path/to/restaurant-mcp",
      "env": {
        "RESTAURANT_MCP_KEY": "your-generated-master-key"
      }
    }
  }
}

Replace paths with the actual paths from the setup output.

5. (Optional) Remote Hosting via Docker

For access from Claude.ai, Claude Code, or mobile — run the server on a home server / NAS / Raspberry Pi:

# Copy env template and fill in values from setup
cp .env.example .env
# Edit .env — add MCP_AUTH_TOKEN, RESTAURANT_MCP_KEY, and TUNNEL_TOKEN

# Build and start
docker compose up --build -d

# Verify
curl http://localhost:8000/health
# → {"status":"ok"}

Then configure Claude Desktop for remote access:

{
  "mcpServers": {
    "restaurant": {
      "url": "https://mcp.yourdomain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

Or Claude Code:

claude mcp add restaurant --transport streamable-http \
  --url https://mcp.yourdomain.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

See Remote Hosting Spec for full Cloudflare Tunnel setup instructions.

6. Restart Claude Desktop

Quit and reopen Claude Desktop. You should see the restaurant tools available (hammer icon in the chat input).

7. First Run — Set Up Your Profile

Start a conversation with Claude:

You: "Help me set up my restaurant preferences"

Claude: Let's get you set up! First, what's your home address?
        (I'll use this as "near home" when you search)

You: "123 Main St, New York, NY 10001"

Claude: Got it. Where do you work?

You: "456 Park Ave, New York, NY 10022"

Claude: What are your favorite cuisines?

You: "Italian, Japanese, Mexican"

Claude: Any dietary restrictions?

You: "None for me"

Claude: ✓ Profile saved! You're all set.

8. Add Dining Companions

You: "Add my wife — she has a nut allergy and a seed allergy"

Claude: ✓ Saved! I'll remember her allergies when searching restaurants.

You: "Create a group called 'date night' with my wife"

Claude: ✓ Group 'date night' created. Merged restrictions: nut allergy, seed allergy.

Security Model

Install the optional keyring dependency for OS keyring support (legacy mode):

pip install -e ".[security]"

Example Prompts

Discovery

• "Find Italian restaurants near home"

• "What's good for dinner near work tonight?"

• "Show me highly-rated sushi places within walking distance"

• "Find restaurants good for a group of 6 near Union Square"

Booking

• "Check availability at Carbone for Saturday at 7 PM, party of 2"

• "Book L'Artusi for Friday at 8, party of 4"

• "What reservations do I have coming up?"

• "Cancel my reservation at Via Carota"

Group Dining

• "Find a restaurant for date night this Saturday"

• "Search for a place that works for the whole family — remember everyone's allergies"

Recommendations

• "What should we try tonight? We haven't been out in a week"

• "Recommend something new — I'm tired of Italian"

• "What's good for outdoor dining today?" (checks weather automatically)

History & Preferences

• "Log that we went to Lilia last night — it was amazing, 5 stars"

• "Where have we eaten in the last month?"

• "Update my preferences — add Thai to my favorite cuisines"

• "Blacklist TGI Friday's — never suggest it again"

Cost Tracking

• "How much have I spent on API calls this month?"

MCP Tools (22 total)

API Costs

Estimated monthly cost for heavy use: $3-8 (with caching)

Use api_costs to monitor your spending at any time.

Architecture

Technical Stack

• Language: Python 3.11+

• Framework: FastMCP — auto-generates tool schemas from type hints

• Transport: stdio (local) or streamable-http (remote hosting)

• Storage: SQLite (local, WAL mode) with aiosqlite

• Auth: Bearer token via FastMCP's TokenVerifier (constant-time comparison)

• Browser Automation: Playwright (for auth + OpenTable)

• APIs: Google Places (New), OpenWeatherMap, Resy (unofficial), OpenTable (automation)

• Calendar: Google Calendar URL generation (zero-config)

• Containerization: Docker + Cloudflare Tunnel for remote hosting

• Resilience: tenacity (retry), custom CircuitBreaker, InMemoryCache (LRU + TTL)

Resilience Features

• Retry with exponential backoff — transient errors (429, 5xx) are automatically retried up to 3 times

• Circuit breakers — per-service (Resy, Google Places, OpenTable, Weather) to prevent hammering failed APIs

• 3-layer booking fallback — Resy API -> OpenTable Playwright -> deep links with manual instructions

• In-memory caching — LRU cache with TTL for search results, reducing API costs

• User-friendly errors — all exceptions are mapped to actionable messages for Claude to relay

Project Structure

restaurant-mcp/
├── .ai/
│   ├── AGENTS.md               # Agent instructions
│   └── ENGINEERING-STANDARDS.md # Code patterns, testing mandate
├── docs/
│   ├── specs/                   # EPICs, architecture plan, research
│   └── adr/                     # Architecture Decision Records
├── scripts/
│   ├── validate.sh              # Full validation: lint + test + coverage
│   ├── test.sh                  # Run tests with coverage
│   └── lint.sh                  # Ruff linting only
├── src/
│   ├── server.py                # FastMCP entry point + health endpoint
│   ├── auth.py                  # Bearer token verifier for remote access
│   ├── config.py                # Environment configuration
│   ├── models/                  # Pydantic data models
│   ├── storage/                 # SQLite + encrypted credentials
│   ├── clients/                 # API clients + resilience + cache
│   ├── matching/                # Cross-platform venue ID resolution
│   └── tools/                   # MCP tool definitions
├── tests/                       # 1193 tests, 100% branch coverage
├── data/                        # Runtime: DB, logs, credentials (gitignored)
├── Dockerfile                   # Container build for remote hosting
├── docker-compose.yml           # MCP + Cloudflare Tunnel orchestration
├── pyproject.toml
├── .env.example
└── README.md

Development

# Activate virtual environment
source .venv/bin/activate

# Run full validation (lint + tests + coverage + import check)
bash scripts/validate.sh

# Run tests only
bash scripts/test.sh

# Run linter only
bash scripts/lint.sh

Testing: 1193 unit tests with 100% branch coverage (fail_under = 100 enforced).

Integration Tests

On-demand integration tests exercise the full stack against live Resy and OpenTable APIs:

# Run all integration tests
python -m pytest tests/integration/ -m integration -v

# Resy only
python -m pytest tests/integration/test_resy_integration.py -m integration -v

# OpenTable only (requires session cookies — see step 9 above)
python -m pytest tests/integration/test_opentable_integration.py -m integration -v

# With a specific restaurant / date
INTEGRATION_RESTAURANT="Lilia" INTEGRATION_DATE="2026-03-15" \
  python -m pytest tests/integration/ -m integration -v

Integration tests are excluded from validate.sh and default pytest runs. They require real credentials in the credential store (set up via python -m src.setup).

Prior Art

Several MCP restaurant reservation servers already exist — these serve as reference implementations:

What we add: Full Google Places integration, weather-aware outdoor seating, dining companion dietary tracking, visit history with reviews, and true dual-platform booking (Resy + OpenTable).

Documentation

Risks & Mitigations

Legal Considerations

The NY Restaurant Reservation Anti-Piracy Act (S.9365A, effective February 2025) prohibits third-party services from listing or selling restaurant reservations without written restaurant agreements. Penalties: $1,000/violation/day.

For this project: Personal-use automation is not explicitly prohibited, but both Resy's and OpenTable's Terms of Service prohibit automated access. This is a personal tool, not a commercial service.

Future Ideas

• LA expansion (after NYC is stable)

• Shared preferences with partner (two-user mode)

• Restaurant deal tracking (NYC Restaurant Week, etc.)

• Tock integration (ticketed dining experiences)

• Yelp integration (official MCP server exists with booking support)

• Google Calendar API (OAuth2) for automatic sync (currently URL-based)

• SQLite cache tier for cross-session persistence

Status: All 8 EPICs complete. Remote hosting via Docker + Cloudflare Tunnel. 1193 tests, 100% branch coverage. Integration tests for Resy and OpenTable.