Documentation
Connect your AI agent to real-time LCBO product, inventory, and sales data.
Quick Start
Using Claude (web, Desktop or mobile)? No key needed — add BoozeData as a connector and sign in when prompted (see Claude.ai setup).
Get up and running in under a minute. You need a BoozeData API key — sign up free to get one.
$ claude mcp add boozedata \
https://boozedata.ca/mcp \
--header "Authorization: Bearer YOUR_API_KEY"That's it. Claude (or any MCP client) can now search products, check inventory, and query sales data.
MCP Setup
BoozeData implements the Model Context Protocol (MCP) — an open standard for connecting AI agents to data sources. Any MCP-compatible client can connect.
Claude Code
$ claude mcp add boozedata \
https://boozedata.ca/mcp \
--header "Authorization: Bearer YOUR_API_KEY"Claude (Web, Desktop & Mobile)
Add BoozeData once as a connector and it works across claude.ai, Claude Desktop and the Claude mobile apps.
- Go to Settings → Connectors → Add Custom Connector
- Enter name:
BoozeData - Enter URL:
https://boozedata.ca/mcp - Click Add
- Claude opens the BoozeData sign-in page. Sign in or create a free account (email and password, or Google)
- Review the consent screen and click Approve. You'll be returned to Claude and the BoozeData tools are ready to use
No account or API key is needed beforehand. If you don't have an API key yet, one named Claude connector is created for you automatically during connect. You can view or revoke it any time on the API keys page. Prefer to use your own key? Choose Use an API key instead on the consent screen.
Claude.ai uses OAuth behind the scenes, so you never paste credentials into Claude.
Claude Desktop
Claude Desktop uses the same connector. Add it with the steps above (or go to Settings → Connectors in the Desktop app) and sign in when prompted.
Cursor
In Cursor settings, add a new MCP server:
{
"mcpServers": {
"boozedata": {
"url": "https://boozedata.ca/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}ChatGPT
In ChatGPT settings, go to Connections → Add MCP Server, and enter:
- URL:
https://boozedata.ca/mcp - Auth header:
Authorization: Bearer YOUR_API_KEY
MCP Tools
BoozeData exposes 11 tools via MCP. Your AI agent calls these automatically based on your questions.
search_productsSearch and filter the product catalog (LCBO has ~11,000 active products; further retailers appear once launched).
| Parameter | Type | Description |
|---|---|---|
| retailer | string | Optional retailer code, e.g. "lcbo" (default: every available retailer; see get_scrape_status) |
| query | string | Text search across name, brand, and description |
| category | string | Category filter: "Gin", "Red Wine", "IPA", etc. |
| booze_type | string | "Wine", "Spirits", "Beer & Cider", "Coolers" |
| country | string | "Canada", "France", "Japan" |
| region | string | "Ontario", "Niagara Peninsula", "Speyside" |
| min_price / max_price | number | Price range filter |
| min_abv / max_abv | number | ABV range filter |
| sort_by | string | "name", "price", "sell_rank_yearly", "sell_rank_monthly" |
| limit / offset | number | Pagination (max 100) |
Example
{ "category": "Gin", "region": "Ontario", "sort_by": "sell_rank_yearly", "sort_order": "asc" }Returns: products[] (each with retailer, retailer_name, retailer_sku), count, offset, limit
get_productGet full details for a single product by SKU.
| Parameter | Type | Description |
|---|---|---|
| sku | string | Product SKU, e.g. "447540" |
Example
{ "sku": "447540" }Returns: product (all fields including description, tasting notes)
get_product_inventoryGet per-store inventory for a product. Shows which stores stock it and quantities.
| Parameter | Type | Description |
|---|---|---|
| sku | string | Product SKU |
| city | string | Filter by city, e.g. "Toronto" |
| date | string | Date (YYYY-MM-DD), defaults to today |
| limit | number | Max results (max 200) |
Example
{ "sku": "447540", "city": "Toronto" }Returns: stores[] (each with retailer, retailer_name, retailer_store_id), total_units, store_count
get_store_inventoryPro onlyGet all products in stock at a specific store.
| Parameter | Type | Description |
|---|---|---|
| store_id | number | Store ID (use search_stores to find) |
| category | string | Filter by category |
| sort_by | string | "quantity", "name", "price" |
Example
{ "store_id": 511, "category": "Gin" }Returns: products[], count
get_salesPro onlyGet sales data for a product over a date range. Computed from daily inventory depletion.
| Parameter | Type | Description |
|---|---|---|
| sku | string | Product SKU |
| retailer | string | Optional retailer code, e.g. "lcbo" (default: every available retailer; see get_scrape_status) |
| start_date | string | Start date (YYYY-MM-DD) |
| end_date | string | End date, defaults to today |
| aggregate | string | "daily" for per-day breakdown, "total" for sum |
| store_id | number | Filter by specific store |
Example
{ "sku": "447540", "start_date": "2026-03-01", "aggregate": "total" }Returns: total_sold, stores_with_sales, days_with_data (or daily breakdown)
get_top_sellersPro onlyGet best-selling products by actual units sold in a date range.
| Parameter | Type | Description |
|---|---|---|
| retailer | string | Optional retailer code, e.g. "lcbo" (default: every available retailer; see get_scrape_status) |
| start_date | string | Start date (YYYY-MM-DD) |
| category | string | Filter by category |
| booze_type | string | Filter by type |
| query | string | Text filter on product name/brand |
| store_id | number | Filter by store |
Example
{ "start_date": "2026-03-01", "category": "Gin", "limit": 10 }Returns: top_sellers[] (sku, retailer, retailer_name, name, total_sold, store_count)
search_storesSearch stores by name, address, city or store number.
| Parameter | Type | Description |
|---|---|---|
| retailer | string | Optional retailer code, e.g. "lcbo" (default: every available retailer; see get_scrape_status) |
| query | string | Search name/address/store number, e.g. "Queen" or "511" |
| city | string | "Toronto", "Ottawa", "Guelph" |
Example
{ "city": "Toronto" }Returns: stores[] (store_id, retailer, retailer_name, retailer_store_id, name, city, address, phone)
get_categoriesGet the full product category taxonomy with counts.
| Parameter | Type | Description |
|---|---|---|
| retailer | string | Optional retailer code, e.g. "lcbo" (default: every available retailer; see get_scrape_status) |
Example
{}Returns: tree[], varietals[], subregions[], programs[]
get_scrape_statusCheck the health and freshness of the scraped data, per retailer.
Example
{}Returns: retailers[] (one entry per available retailer: retailer, retailer_name, status, run_date, completed_at, data_freshness_hours, ...); top-level latest_run and data_freshness_hours still describe LCBO
get_inventory_historyPro onlyGet aggregated inventory history for a product over time. Shows total units and store count per day.
| Parameter | Type | Description |
|---|---|---|
| sku | string | Product SKU |
| start_date | string | Start date (YYYY-MM-DD), defaults to 30 days ago |
| end_date | string | End date (YYYY-MM-DD), defaults to today |
| limit | number | Max days to return (max 365, default 90) |
Example
{ "sku": "447540", "start_date": "2026-02-01" }Returns: days[] (summary_date, store_count, total_units)
get_store_product_historyPro onlyGet per-store inventory history for a specific product at a specific store. Shows daily quantity snapshots.
| Parameter | Type | Description |
|---|---|---|
| sku | string | Product SKU |
| store_id | number | Store ID (use search_stores to find) |
| start_date | string | Start date (YYYY-MM-DD), defaults to 30 days ago |
| end_date | string | End date (YYYY-MM-DD), defaults to today |
Example
{ "sku": "447540", "store_id": 511 }Returns: store_name, city, days[] (scraped_date, quantity)
REST API
All MCP tools are also available as REST endpoints. Authenticate with your API key or Supabase JWT in the Authorization: Bearer header.
View the interactive API reference →
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://boozedata.ca/api/v1/products?query=gin&category=Gin&sort_by=sell_rank_yearly&limit=5"
Access Tiers
| Feature | Free | Pro ($100/mo) |
|---|---|---|
| Rate limit | 20 rpm / 100 rpd | 100 rpm / 5,000 rpd |
| Product search & details | Yes | Yes |
| Current inventory (per product) | Yes | Yes |
| Whole-store inventory (get_store_inventory) | No | Yes |
| Store lookup | Yes | Yes |
| Categories | Yes | Yes |
| MCP + REST API | Yes | Yes |
| OAuth support | Yes | Yes |
| Sales rankings (sort) | No | Yes |
| Sales data (get_sales) | No | Yes |
| Top sellers (get_top_sellers) | No | Yes |
| Inventory history | No | Yes |
| Store-level inventory history | No | Yes |
| Tasting notes / description | No | Yes |
| Promo / sale price data | No | Yes |
| Sugar content | No | Yes |
Free tier users receive redacted product data — fields like sell_rank_yearly, description, ec_promo_price, and sugar_gm_per_ltr are removed from responses. Upgrade to Pro for full access.
Embed Widgets
Add real-time LCBO store inventory to any website with an embeddable widget. Show your visitors which stores carry a product and current stock levels.
<iframe src="https://boozedata.ca/embed/inventory/447540?key=YOUR_API_KEY" width="100%" height="500" style="border: none; border-radius: 8px;" loading="lazy" ></iframe>
View the full widget documentation →