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.

Fair play

These tools are for working with the data — looking things up, comparing releases, analysing a market — not for extracting it. A question about a bottle, a distillery, or a price trend is the normal case; a client that walks the whole database page by page is not.

• Ask narrow questions. Query the bottles and distilleries you actually care about. Paging through everything “just in case” is what makes the limits tighter for everybody.
• Do not ask twice. Reuse what a tool already returned within a session instead of repeating the same call.
• No mirroring or resale. Bulk export, rebuilding the dataset elsewhere, re-publishing the results, or feeding them into another product is outside what these endpoints are offered for.
• The limits are real. What is counted is how much data leaves, not how often you ask: a budget of units over a rolling 30-day window, a daily ceiling within it, a per-search page allowance, and rate limits — all per account and per plan. A row of results costs more or less depending on how expensive that data is, and failed calls cost nothing. Every answer reports what is left, so a client can pace itself. A refusal is an answer — retrying straight through one temporarily parks the account, suspending its MCP access briefly.
• One token, one account. Do not share it or wire it into a public service.

Full rules: Terms & Conditions.

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 five scope-specific search tools that share the same syntax: search_past_auction_lots, search_live_auction_lots, search_retail_listings, search_casks, and search_bottles. search_casks is the one tool whose search terms are optional — call it with no arguments to page through the whole cask list.

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 Bearer credential in the Authorization header: your MCP API token, or the access token an assistant receives when you connect it by signing in.

Connect by signing in (Claude, ChatGPT)

No token to copy. In the assistant's connector settings, add a custom connector with this address:

https://whiskyhunter.net/mcp

The assistant sends you to Whisky Hunter to log in and approve the connection, then works under your account and your plan's data allowance. You need a Whisky Hunter account first.

Connect with a token (Claude Desktop / Claude Code and other clients)

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. Assistants that connect by signing in use OAuth 2.1 (authorization code with PKCE) and need no token from you. Unauthenticated requests will receive a 401 Unauthorized JSON-RPC error.