saq-mcp

saq-mcp

A Model Context Protocol server for SAQ.com (Société des alcools du Québec).

Search wines and spirits, track new arrivals, monitor restocks, and filter alerts by geographic area — all from Claude or any MCP-compatible client.

Features

| Tool | Description | |---|---| | search_products | Full-text search with filters: category, country, region, grape, price, availability | | get_product | Product details by SKU (country, region, grape, ABV, sugar, taste profile, rating, store count) | | get_new_arrivals | Products sorted by arrival date, optionally filtered by category | | get_coming_soon | Products with "Available shortly" or "Lottery soon" status | | check_store_availability | Which stores currently carry a product | | watch_product | Add a SKU to the restock watchlist | | unwatch_product | Remove from watchlist | | watch_all | Monitor the entire SAQ catalog (~35k products) for any restock | | unwatch_all | Disable catalog-wide monitoring | | check_restocks | Manually trigger a restock check for all watched products | | list_watched | Show watchlist status and last snapshot | | set_location_filter | Restrict restock alerts to stores within a radius of a city or coordinates | | clear_location_filter | Remove geographic filter |

How it works

SAQ's website runs on Adobe Commerce with the Live Search catalog service. On first run, a headless Chromium browser intercepts an outgoing request to catalog-service.adobe.io to extract the public API key, which is then cached locally. All subsequent calls go directly to the GraphQL endpoint — no browser overhead.

Restock detection compares each product's store_availability_list (a full list of store IDs returned inline by the search API) against a saved snapshot. A restock fires when new store IDs appear or availability status improves (e.g. Sold out → In store).

Requirements

• Node.js 20+
• macOS (for the launchd agent; the MCP server itself is cross-platform)

Installation

git clone https://github.com/MonoPaul/saq-mcp.git
cd saq-mcp
npm install
npx playwright install chromium   # one-time: downloads headless browser
npm run build

Add to Claude Code

Add to ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "saq": {
      "command": "node",
      "args": ["/path/to/saq-mcp/dist/index.js"]
    }
  }
}

Schedule daily restock checks (macOS)

bash install.sh

This fills in the com.saq-mcp.watcher.plist.template with your local paths, writes it to ~/Library/LaunchAgents/, and loads it with launchctl. The watcher runs daily at 05:30 and sends a macOS notification for any restock detected.

You can also run it manually at any time:

node dist/watcher.js --notify

Geographic filtering

Restock alerts can be scoped to stores within a configurable radius:

# In Claude:
set_location_filter city="Montréal" radius_km=30

The city is geocoded using SAQ's own store directory (no external geocoding API). The filter applies to both individually watched products and the full catalog scan.

Data stored locally

All runtime data lives in ~/.saq-mcp/:

| File | Contents | |---|---| | credentials.json | Cached API key (extracted once from the SAQ website) | | watchlist.json | Watched SKUs, store snapshots, location filter | | catalog-snapshot.json | Full catalog snapshot for watch-all mode | | stores.json | SAQ store directory with coordinates (refreshed weekly) | | restock.log | Append-only log of every watcher run |

None of these files are committed to git.

License

MIT