Pour Picks 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):

{
  "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

{
  "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:

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):

{
  "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

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.