vivino-mcp 0.1.0

MCP server that fetches wine information from Vivino

vivino-mcp

An MCP server that fetches wine information from Vivino via its unofficial JSON API.

⚠️ Vivino has no official public API. This server calls internal endpoints the website uses. It is intended for personal / educational use. Respect Vivino's Terms of Service and keep request volume low (the server caches and throttles by default). Endpoints may change without notice.

Tools

Tool	Description
search_wine(query, limit)	Search wines by name; returns summary cards.
search_by_filters(wine_type, country, min_rating, price_min, price_max, limit)	Discover wines by structured filters.
get_wine_details(vintage_id)	Full details for a vintage incl. taste structure (tannin/acidity/sweetness/intensity) and flavor profile.
get_wine_reviews(wine_id, year, limit)	User reviews for a wine.
list_wine_types()	Supported wine types and their Vivino ids.

IDs flow naturally: a search result gives you vintage_id (for details) and wine_id (for reviews).

Setup

uv sync
uv run python smoke_test.py   # optional: live end-to-end check

Run

uv run vivino-mcp

Register with an MCP client (e.g. Claude Desktop)

{
  "mcpServers": {
    "vivino": {
      "command": "uv",
      "args": ["--directory", "/Users/dmkim/Projects/vivino-mcp", "run", "vivino-mcp"]
    }
  }
}

Configuration (env vars)

Var	Default	Purpose
VIVINO_CURRENCY	USD	Currency for prices/explore.
VIVINO_COUNTRY	us	Default country code.
VIVINO_USER_AGENT	Firefox UA	Override the browser UA sent to Vivino.

Architecture

server.py   MCP tool layer (FastMCP) — schemas + error wrapping
   │
client.py   VivinoClient — throttle, retry/backoff, TTL cache
   │
models.py   Pydantic models — flatten Vivino's nested JSON
config.py   UA, currency, timeouts, cache TTLs, wine-type map

Verified Vivino endpoints

• GET /api/explore/explore — search/discovery. Params: country_codes[], wine_type_ids[], grape_ids[], region_ids[], min_rating, price_range_min/max, currency_code, order_by, order, page. Results at explore_vintage.matches[].
• GET /api/vintages/{vintage_id} — vintage detail (no taste data).
• GET /api/wines/{wine_id}/tastes — taste structure + flavor profile.
• GET /api/wines/{wine_id}/reviews?per_page=&page=&year= — user reviews.

A browser User-Agent header is required — Vivino blocks requests without one.

Notes / limitations

• search_wine ranks explore results client-side by name match (the explore path has no free-text q param). For exact-name lookups this is approximate; extend with the site search host if you need stricter matching.
• No tests beyond smoke_test.py (which hits the live API). Add HTML/JSON fixtures for offline unit tests before relying on this in CI.