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

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

search_wine / search_by_filters return {total_matched, returned, note, results}. total_matched is how many wines Vivino reports for the query; results is a ranked, paginated list capped at limit (not the full catalog).

Install (for users)

Claude Desktop — one-click

Download vivino-mcp.mcpb from the latest release and double-click it (or Settings → Extensions → Install from file). Requires uv on your machine.

Any MCP client — via uvx

No clone needed; uvx fetches the package from PyPI automatically:

{
  "mcpServers": {
    "vivino": {
      "command": "uvx",
      "args": ["vivino-mcp"]
    }
  }
}

Optional env: VIVINO_CURRENCY (default USD), VIVINO_COUNTRY (default us).

Develop (from source)

uv sync
uv run python smoke_test.py   # optional: live end-to-end check
uv run vivino-mcp             # run the server (stdio)

Configuration (env vars)

TLS behind a corporate proxy

By default the server verifies TLS against your OS trust store (via truststore), so it works behind corporate TLS-interception proxies whose private root CA is in the system keychain. If you still hit CERTIFICATE_VERIFY_FAILED, point VIVINO_CA_BUNDLE at your company's root CA PEM, or set VIVINO_INSECURE=1 as a last resort.

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.