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.

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. Restart Claude Desktop

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

6. 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.

7. 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
• Storage: SQLite (local, WAL mode) with aiosqlite
• Browser Automation: Playwright (for auth + OpenTable)
• APIs: Google Places (New), OpenWeatherMap, Resy (unofficial), OpenTable (automation)
• Calendar: Google Calendar URL generation (zero-config)
• 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
│   ├── 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/                       # 1112 tests, 100% branch coverage
├── data/                        # Runtime: DB, logs, credentials (gitignored)
├── 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: 1112 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. 1112 tests, 100% branch coverage. Integration tests for Resy and OpenTable.