Pour Picks

Official8 tools

by bguillow-rgb · TypeScript

Search the Pour Picks bourbon & whiskey database: 4,700+ bottles with tasting profiles and prices.

MCP Server: io.github.bguillow-rgb/pour-picks

This MCP server provides read-only search access to the Pour Picks bourbon & whiskey database. It supports querying 4,700+ bottles with tasting profiles, prices, pairings, and community ratings through MCP-compatible AI clients.

🛠️ Key Features

Read-only access to 4,700+ bottles
Full-text catalog search with category, price, and proof filters
Structured bottle records including tasting profiles, prices, pairings, and community ratings
Tooling exposed: 8 tools

🚀 Use Cases

Find bourbon and whiskey by text plus category/price/proof constraints
Retrieve a single bottle’s full record for tasting and pairing details
Use community ratings alongside tasting profiles

⚡ Developer Benefits

Integrates with Claude or any MCP-compatible AI client
Deterministic tool functions: search_bottles and get_bottle
get_bottle fetches by ID or name

⚠️ Limitations

Read-only access (no updates to the Pour Picks database)

Topics

agent-toolsai-agentsbourbonmcpmcp-servermodel-context-protocolrecommendationswhiskeygemini-cli-extension

Captured live from the server via tools/list.

search_bottles

Full-text search across 4,700+ bourbons, ryes, scotches, and other spirits in the Pour Picks database. Filter by category, price (USD), and proof. Returns structured tasting profiles with source attribution.

Parameters7

query	string	optional	Free-text search: distillery, bottle name, or expression
category	string	optional	Spirit category filter
price_min	number	optional	Minimum price in USD
price_max	number	optional	Maximum price in USD
proof_min	number	optional	Minimum proof
proof_max	number	optional	Maximum proof
limit	integer	optional	Max results (default 10, max 10)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 120,
      "description": "Free-text search: distillery, bottle name, or expression"
    },
    "category": {
      "type": "string",
      "enum": [
        "bourbon",
        "rye",
        "tennessee",
        "wheat",
        "corn",
        "american_single_malt",
        "scotch_single_malt",
        "scotch_blend",
        "irish",
        "japanese",
        "canadian",
        "world_whisky",
        "rum",
        "tequila",
        "mezcal",
        "cognac",
        "armagnac",
        "brandy",
        "gin",
        "vodka",
        "other"
      ],
      "description": "Spirit category filter"
    },
    "price_min": {
      "type": "number",
      "minimum": 0,
      "description": "Minimum price in USD"
    },
    "price_max": {
      "type": "number",
      "minimum": 0,
      "description": "Maximum price in USD"
    },
    "proof_min": {
      "type": "number",
      "minimum": 0,
      "description": "Minimum proof"
    },
    "proof_max": {
      "type": "number",
      "minimum": 0,
      "description": "Maximum proof"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 10, max 10)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_bottle

Detailed record for one bottle: tasting profile, flavor notes, pairings, price, community ratings. Accepts a Pour Picks bottle ID (UUID) or a bottle name.

Parameters1

slug_or_id

string

required

Bottle UUID or a name like 'Eagle Rare 10'

Raw schema

{
  "type": "object",
  "properties": {
    "slug_or_id": {
      "type": "string",
      "maxLength": 120,
      "description": "Bottle UUID or a name like 'Eagle Rare 10'"
    }
  },
  "required": [
    "slug_or_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

find_similar

Bottles with a similar flavor profile to a given bottle, ranked by shared flavor notes and body/sweetness/char proximity. Deterministic scoring over the Pour Picks structured tasting data.

Parameters2

bottle_id	string	required	Bottle UUID or name
limit	integer	optional	Max results (default 5)

Raw schema

{
  "type": "object",
  "properties": {
    "bottle_id": {
      "type": "string",
      "maxLength": 120,
      "description": "Bottle UUID or name"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 5)"
    }
  },
  "required": [
    "bottle_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

find_cheaper_alternative

Bottles in the same style with a similar flavor profile at a lower price than the given bottle. Great for 'what tastes like X without the price tag' questions.

Parameters2

bottle_id	string	required	Bottle UUID or name
limit	integer	optional	Max results (default 5)

Raw schema

{
  "type": "object",
  "properties": {
    "bottle_id": {
      "type": "string",
      "maxLength": 120,
      "description": "Bottle UUID or name"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 5)"
    }
  },
  "required": [
    "bottle_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_recommendations

Personalized bottle picks from taste preferences (flavor keywords like 'caramel', 'smoke', 'cherry'), a budget in USD, and an occasion (e.g. 'gift', 'everyday sipper', 'celebration', 'introducing a friend to bourbon').

Parameters5

taste_preferences	array	required	Flavor keywords the drinker enjoys, e.g. ['caramel','vanilla','oak']
budget	number	optional	Max price in USD
occasion	string	optional	What the bottle is for
category	string	optional	Restrict to one spirit category
limit	integer	optional	Max results (default 5)

Raw schema

{
  "type": "object",
  "properties": {
    "taste_preferences": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      },
      "minItems": 1,
      "maxItems": 20,
      "description": "Flavor keywords the drinker enjoys, e.g. ['caramel','vanilla','oak']"
    },
    "budget": {
      "type": "number",
      "minimum": 0,
      "description": "Max price in USD"
    },
    "occasion": {
      "type": "string",
      "maxLength": 120,
      "description": "What the bottle is for"
    },
    "category": {
      "type": "string",
      "enum": [
        "bourbon",
        "rye",
        "tennessee",
        "wheat",
        "corn",
        "american_single_malt",
        "scotch_single_malt",
        "scotch_blend",
        "irish",
        "japanese",
        "canadian",
        "world_whisky",
        "rum",
        "tequila",
        "mezcal",
        "cognac",
        "armagnac",
        "brandy",
        "gin",
        "vodka",
        "other"
      ],
      "description": "Restrict to one spirit category"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 5)"
    }
  },
  "required": [
    "taste_preferences"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

compare_bottles

Side-by-side comparison of two bottles: proof, age, price, flavor profile, shared and distinct tasting notes, and community ratings.

Parameters2

bottle_a	string	required	First bottle — UUID or name
bottle_b	string	required	Second bottle — UUID or name

Raw schema

{
  "type": "object",
  "properties": {
    "bottle_a": {
      "type": "string",
      "maxLength": 200,
      "description": "First bottle — UUID or name"
    },
    "bottle_b": {
      "type": "string",
      "maxLength": 200,
      "description": "Second bottle — UUID or name"
    }
  },
  "required": [
    "bottle_a",
    "bottle_b"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

trending_bottles

Bottles Pour Picks users are adding to their cellars most over the last 30 days (falls back to catalog popularity when live activity data is unavailable). The method used is labeled in the response.

Parameters1

limit

integer

optional

Max results (default 10, max 10)

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 10, max 10)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

pour_tonight_suggestion

A pour suggestion for right now, based on mood (e.g. 'unwinding', 'celebratory', 'contemplative'), occasion (e.g. 'nightcap', 'with friends', 'after dinner'), and season.

Parameters3

mood	string	optional	How you're feeling
occasion	string	optional	The setting
season	string	optional	Season to weight the pick toward — heavier, warming pours in winter; lighter in summer

Raw schema

{
  "type": "object",
  "properties": {
    "mood": {
      "type": "string",
      "maxLength": 120,
      "description": "How you're feeling"
    },
    "occasion": {
      "type": "string",
      "maxLength": 120,
      "description": "The setting"
    },
    "season": {
      "type": "string",
      "enum": [
        "winter",
        "spring",
        "summer",
        "fall"
      ],
      "description": "Season to weight the pick toward — heavier, warming pours in winter; lighter in summer"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md5 KBView on GitHub

Pour Picks MCP Server

Query the Pour Picks bourbon & whiskey database from Claude, or any MCP-compatible AI client. Read-only access to 4,700+ bottles with structured tasting profiles, prices, pairings, and community ratings.

Pour Picks is the bourbon collector's journal for iOS — get it on the App Store.

Tools

Tool	What it does
`search_bottles`	Full-text catalog search with category, price, and proof filters
`get_bottle`	Full record for one bottle (by ID or name): tasting profile, price, pairings, community ratings
`find_similar`	Bottles with a similar flavor profile, ranked by shared notes and body/sweetness/char proximity
`find_cheaper_alternative`	Same style, similar profile, lower price
`get_recommendations`	Picks from flavor preferences + budget + occasion
`compare_bottles`	Side-by-side: proof, age, price, shared and distinct flavors, ratings
`trending_bottles`	What Pour Picks users are adding to their cellars right now
`pour_tonight_suggestion`	A pour for tonight, from mood, occasion, and season

Every response includes source attribution, a citation-ready summary line, links, and data freshness dates. All scoring is deterministic — no AI calls happen inside the server.

Install (Claude Desktop)

Requires Node.js 18+.

Add to your claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config):

json

{
  "mcpServers": {
    "pour-picks": {
      "command": "npx",
      "args": ["-y", "pour-picks-mcp"]
    }
  }
}

Restart Claude Desktop. No API key or configuration needed — the server ships with public read-only access.

From a local checkout

json

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

Configuration (optional)

The server works with zero configuration using Pour Picks' public read-only key. Environment variables override the defaults:

Variable	Purpose
`SUPABASE_URL`	Override the database URL
`SUPABASE_SERVICE_ROLE_KEY`	Internal use only — unlocks live 30-day cellar-add trending. Never distribute this key.

Without the service key, trending_bottles falls back to catalog popularity and labels the method in its response (method: "catalog_popularity_tier" vs "cellar_adds_last_30_days").

Remote endpoint (no install)

Streamable HTTP for web agents and MCP clients that take a URL:

code

https://nqnigdqkcvrziwcbgily.supabase.co/functions/v1/mcp

Also listed on Smithery (gateway pour-picks--bguillow.run.tools) and the official MCP registry as io.github.bguillow-rgb/pour-picks.

Example agent requests

Questions an agent can answer with these tools:

"What bourbon is similar to Eagle Rare but easier to find?" → find_similar
"Recommend a bourbon under $60 with vanilla, oak, and caramel notes." → get_recommendations with taste_preferences: ["vanilla","oak","caramel"], budget: 60
"What tastes like Blanton's without the price tag?" → find_cheaper_alternative
"Compare Eagle Rare and Buffalo Trace." → compare_bottles
"What bourbon should I pour on a cold night?" → pour_tonight_suggestion with season: "winter"
"What bottles are collectors adding right now?" → trending_bottles

Example response shape (truncated):

json

{
  "cheaper_alternatives": [
    { "name": "Buffalo Trace W.L. Weller 12 Year", "price_usd": 49.99,
      "similarity": 0.78, "savings_usd": 15.0,
      "shared_flavors": ["caramel", "oak"] }
  ],
  "attribution": {
    "source": "Pour Picks — The Bourbon Collector's Journal",
    "links": { "website": "https://pourpicks.app/" }
  }
}

Development

bash

npm install
npm run dev     # run from TypeScript via tsx
npm run build   # compile to dist/
npm start       # run compiled server

The server speaks MCP over stdio. Catalog access is read-only by construction: every query path issues SELECTs against tables that are publicly readable under row-level security, and it is rate-limited to 60 calls/minute.

Usage telemetry: each tool call logs the tool name, its arguments, client name/version, duration, and success/failure to a write-only log table (insert-only under RLS; contents are not publicly readable). No user identity, account data, or conversation content is collected. Logging is fire-and-forget and never affects responses.

Publishing

npm: npm publish from this directory (the mcpName field in package.json links the package to the registry entry).
MCP Registry: server.json in this directory is the registry manifest. Publish with the mcp-publisher CLI after the npm package is live: mcp-publisher login github && mcp-publisher publish.

Data & attribution

Bottle data, tasting profiles, and pairings are curated by Pour Picks. Quote freely with attribution:

Source: Pour Picks — The Bourbon Collector's Journal (pourpicks.app)

Community rating counts are included with every rating so you can judge sample size. Freshness dates on each bottle reflect the last enrichment pass.

Install

Tools (8)

search_bottlesget_bottlefind_similarfind_cheaper_alternativeget_recommendationscompare_bottlestrending_bottlespour_tonight_suggestion

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "pour-picks": {
      "command": "npx",
      "args": [
        "-y",
        "pour-picks-mcp@1.0.4"
      ]
    }
  }
}

MCP Server: io.github.bguillow-rgb/pour-picks

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

search_bottles

get_bottle

find_similar

find_cheaper_alternative

get_recommendations

compare_bottles

trending_bottles

pour_tonight_suggestion

Pour Picks MCP Server

Tools

Install (Claude Desktop)

From a local checkout

Configuration (optional)

Remote endpoint (no install)

Example agent requests

Development

Publishing

Data & attribution

Install

Related servers