Whisky Hunter MCP Server

This endpoint implements the Model Context Protocol (MCP) over Streamable HTTP, giving AI assistants read-only access to Whisky Hunter database.

Responses include only data available to the authenticated request.

Data notes

• Monetary auction and distillery statistics are in GBP unless a tool explicitly states otherwise.
• Auction fee fields buyers_fee, sellers_fee, and vat_fee are percentage values; reserve_fee and listing_fee are fixed amounts in the auction house's base_currency.
• Lot count fields count auction lots.
• Monthly statistics are grouped by calendar month.

Search syntax

There are four scope-specific search tools that share the same syntax: search_past_auction_lots, search_live_auction_lots, search_retail_listings, and search_bottles.

Whisky search is full-text matching against lot, listing, or bottle titles, not a natural-language prompt. Auction houses often describe the same bottle with different spelling, punctuation, age wording, batch padding, or volume notation. Build compact queries from the tokens that identify the bottle, inspect the noise, then tighten with exclusions or one more high-confidence variant.

• search_include is the positive query. Separate real title variants with | , for example macallan 18 | macallan eighteen. Within one variant, every word must match.
• search_exclude removes known false positives. Separate exclusions with & , for example mini & miniature & 5cl.
• Use spaces around operators: mini & miniature is correct; mini&miniature is not.
• Prefer meaningful bare tokens: 18 instead of 18 years old, 43 instead of 43%, 700 instead of 700 ml. Keep distinctive vintage, age, ABV, cask, batch, chapter, or edition details when they separate otherwise similar bottles.
• Use cursor with the returned nextCursor to continue paginated results. A cursor is only valid for the same tool and search terms that produced it.

Practical search examples

Same bottle, different age wording

search_include: macallan 18 | macallan eighteen

Same batch, different spelling and zero padding

search_include: aberlour a'bunadh 7 | aberlour abunadh 7 | aberlour a'bunadh 07 | aberlour abunadh 07

Start broad, then exclude visible noise

search_include: scapa 16
search_exclude: 6 & 2 & 2002 & Jutland & Signatory & Douglas & Cask & Macleod

Full-size bottle, not miniatures or samples

search_exclude: mini & miniature & 5cl & 50ml & sample

For the same search habits in the website UI, see Dive into the search functionality of the Whisky Hunter database.

Endpoint

https://whiskyhunter.net/mcp/

All requests must be POST with Content-Type: application/json and a valid MCP API Bearer token in the Authorization header.

Connect with Claude Desktop / Claude Code

Add the following to your claude_desktop_config.json (or .claude/settings.json):

{
  "mcpServers": {
    "whiskyhunter": {
      "type": "http",
      "url": "https://whiskyhunter.net/mcp/",
      "headers": {
        "Authorization": "Bearer <YOUR_MCP_API_TOKEN>"
      }
    }
  }
}

Available Tools

All tools are read-only. Shared units, date granularity, authentication, pagination, and search syntax are documented once above; each tool below lists only its own accepted arguments and response shape.

Quick start - raw JSON-RPC

# 1. Initialize
curl -s -X POST https://whiskyhunter.net/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <wh_mcp_token>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","clientInfo":{"name":"curl","version":"0"}}}'

# 2. Confirm initialization (server replies 202, no body)
curl -s -X POST https://whiskyhunter.net/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <wh_mcp_token>" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. List tools
curl -s -X POST https://whiskyhunter.net/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <wh_mcp_token>" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# 4. Call a tool
curl -s -X POST https://whiskyhunter.net/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <wh_mcp_token>" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_monthly_distillery_stats","arguments":{"distillery_slug":"ardbeg"}}}'

Search example

curl -s -X POST https://whiskyhunter.net/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <wh_mcp_token>" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"search_past_auction_lots","arguments":{"search_include":"macallan 18 | macallan eighteen","search_exclude":"mini & miniature & 5cl"}}}'

Authentication

Create or rotate your MCP API token on the Whisky Hunter profile page. Unauthenticated requests will receive a 401 Unauthorized JSON-RPC error.