Skip to main content
Glama

yandex-lavka-mcp

PyPI Python License: MIT MCP

An MCP server that lets an AI assistant order groceries from Yandex Lavka — search products, build a cart, and place a real order — with an explicit human confirmation before any money is charged.

WARNING

Unofficial. Yandex Lavka has no public API. This project talks to the same private web API that lavka.yandex.ru uses, authenticated with your own Yandex session cookies. It automates your own account, for your own shopping.

  • Not affiliated with or endorsed by Yandex. Using it may violate Yandex's Terms of Service, and the private API can change or be blocked at any time.

  • confirm_order spends real money on your card. Use at your own risk.

  • Provided as is, without warranty (see LICENSE).

What it does

Tool

Charges?

What it does

lavka_status

—

Is the session + location set up?

list_addresses

—

Your saved Lavka addresses, by name.

use_address

—

Switch delivery to a saved address by name.

set_delivery_address

—

Set delivery to any address by text (any city).

set_location

—

Set delivery point by raw lat/lon.

search_products

—

Search the catalog at the current location.

get_product

—

Product detail by id, slug or Lavka link, incl. nutrition (КБЖУ per 100 g / per portion, as the card shows it).

list_categories

—

Catalog menu: category groups with their categories (per storefront).

get_category_group

—

Categories inside one catalog group, by group id.

get_category_products

—

Products in a category + its subcategory shelf counts; optional subcategory filter.

view_cart

—

Show cart + total.

add_to_cart

—

Add an item.

update_cart_item

—

Set exact quantity (0 removes).

clear_cart

—

Empty the cart.

checkout_preview

no

Full summary: items, subtotal, discount, delivery, ETA, payment, total.

list_payment_methods

—

Your saved cards and which is the default.

set_payment_method

—

Choose which card orders charge.

confirm_order

YES

Places the order and charges the default card (or the one set above).

cancel_order

—

Cancel an order by id.

active_orders

—

Currently tracked orders with status/ETA.

order_history

—

Past orders (total, items count, date), paged.

get_order

—

One order in full: items, totals, address, status.

Money safety. Placing an order is a deliberate two-step flow: checkout_preview returns the full summary and charges nothing; confirm_order(confirmed_total) refuses unless a preview was just run and you pass back the exact total it showed. Change the cart and the preview is invalidated — you must preview again.

3-D Secure. confirm_order submits the order and charges the on-file card, then polls payment status. If your bank requires 3-D Secure, payment_status comes back wait_user_action and a redirect_url is returned — open it to finish paying (a headless charge cannot complete 3DS). cancel_order(order_id) cancels.

Multiple locations / cities. Catalog, prices and cart are location-scoped. use_address("Дача") switches to a saved address; set_delivery_address("Казань, улица Баумана, 1", flat="12") works for any address in any city (it geocodes via Lavka's own address search).

Related MCP server: Yango Tech Retail MCP

How it's built

  • Python 3.12+ · FastMCP · httpx.

  • client.py — the async API client (session auth, CSRF, request building, trims huge payloads).

  • endpoints.py — every API path in one place (overridable from config, no code change).

  • server.py — the MCP tools the assistant sees.

The API sits under https://lavka.yandex.ru/api/v1/providers/* (plus /api/v1/orders/submit for placing orders). Requests need the CSRF token from the homepage HTML plus X-Lavka-Web-* headers — the client handles this.

Setup

1. Install

uv venv && uv pip install -e .

2. Provide your Yandex session (one time)

Log into Lavka in your browser first, then get the session cookies into ~/.config/yandex-lavka-mcp/config.json.

macOS — pull cookies straight from Chrome (one Keychain prompt → Allow):

uv pip install -e '.[browser]'
python scripts/extract_chrome_cookies.py          # auto-detects your profile

Any OS — paste the Cookie header from DevTools (Network → any lavka.yandex.ru request → Request Headers → Cookie):

python scripts/import_cookies.py --header "Session_id=...; yandexuid=...; L=..."

Session cookies expire — re-run when calls start failing with "Lavka session is not authorized".

3. Set a delivery location

Copy config.example.json to ~/.config/yandex-lavka-mcp/config.json and edit, or set it from the assistant with use_address / set_delivery_address. The catalog only works once a location is set. Smoke-test:

python scripts/smoke.py "молоко"

4. Register with your assistant

Claude Code:

claude mcp add yandex-lavka -- uv run --directory /path/to/yandex-lavka-mcp yandex-lavka-mcp

Claude Desktop (mcpServers):

{
  "yandex-lavka": {
    "command": "uv",
    "args": ["run", "--directory", "/path/to/yandex-lavka-mcp", "yandex-lavka-mcp"]
  }
}

Remote deploy (order from your phone)

By default the server speaks stdio (local clients). Set YANDEX_LAVKA_MCP_TRANSPORT=streamable-http to expose it over HTTP so a hosted instance can back a claude.ai custom connector (phone / web).

A prebuilt Dockerfile is included. Secrets are injected at runtime — never baked into the image:

docker build -t yandex-lavka-mcp .
docker run -p 8000:8000 \
  -e YANDEX_LAVKA_MCP_TRANSPORT=streamable-http \
  -e YANDEX_LAVKA_MCP_CONFIG_JSON="$(cat ~/.config/yandex-lavka-mcp/config.json)" \
  yandex-lavka-mcp

(The image defaults to stdio; the TRANSPORT env above switches it to HTTP.)

Environment variables

Var

Purpose

YANDEX_LAVKA_MCP_TRANSPORT

stdio (default) or streamable-http.

YANDEX_LAVKA_MCP_HOST / _PORT

Bind address for HTTP (default 0.0.0.0:8000 in Docker).

YANDEX_LAVKA_MCP_CONFIG_JSON

The whole config.json as one secret (instead of a file).

YANDEX_LAVKA_MCP_SPRAVKA

Captcha pass for the server's IP, if Yandex demands one (see Captcha).

Authentication (any OIDC provider)

A public endpoint spends real money, so protect it. claude.ai's custom connector UI only supports OAuth (no static bearer / custom header — that works only in Claude Code/Desktop). This server is a provider-agnostic OAuth 2.1 resource server: point it at any OpenID-Connect provider (Zitadel, Keycloak, Auth0, Google, …) and it validates JWT access tokens against that provider's JWKS and advertises it via OAuth protected-resource metadata.

Enable it by installing the server extra (pip install '.[server]', already in the Docker image) and setting:

Var

Purpose

YANDEX_LAVKA_MCP_OAUTH_ISSUER

Your provider's issuer URL (enables OAuth).

YANDEX_LAVKA_MCP_SERVER_URL

Public URL of this MCP server (the resource).

YANDEX_LAVKA_MCP_OAUTH_AUDIENCE

Expected token audience (optional but recommended).

YANDEX_LAVKA_MCP_OAUTH_SCOPES

Space-separated required scopes (optional).

YANDEX_LAVKA_MCP_OAUTH_SUBJECTS

Allow-list of token subs that may call the server (optional; strongest lock — every request spends your Lavka session).

YANDEX_LAVKA_MCP_OAUTH_JWKS_URL

Override JWKS URL (optional; else discovered).

A network-exposed HTTP transport refuses to start unless OAuth is configured (it spends real money). Set YANDEX_LAVKA_MCP_ALLOW_INSECURE=1 only if you front it with your own auth. Leaving OAuth unset is allowed for loopback/local use.

Session cookies expire; when calls start failing, re-capture them and update the YANDEX_LAVKA_MCP_CONFIG_JSON secret. There is no headless Yandex login. The captcha pass (below) is a separate secret, so it survives this.

Captcha from a server

Yandex may start answering a hosted instance with a captcha — decided by the server's IP, not the session (the same cookies keep working from home). Tools then fail with "Yandex anti-bot returned a captcha". Solve it once through that IP:

ssh -f -N -D 1080 <your-server>     # SOCKS proxy out of the server's IP
uv run --with playwright python scripts/solve_captcha.py --proxy socks5://127.0.0.1:1080

A throwaway Chrome window opens on the captcha; solve it. The script prints the spravka cookie to stdout — set it as the YANDEX_LAVKA_MCP_SPRAVKA secret (pipe it straight in) and restart. It lasts about 30 days; repeat when the captcha error comes back.

Develop

uv pip install -e ".[dev]"
pytest

One account = one cart

Lavka keeps a single server-side cart per account, guarded by an optimistic cartVersion. This server serializes its own cart writes and retries on version conflicts, so parallel tool calls in one session are safe. But don't drive the same Yandex account from two places at once (e.g. this server and a second MCP session, and the Lavka app): they all write the one shared cart, and you'll see items from the other writer appear in yours. Use a single client at a time.

Security & privacy

  • Cookies and address live only in ~/.config/yandex-lavka-mcp/config.json (chmod 600), git-ignored. Never commit them.

  • The server never adds payment methods or changes account settings.

  • Ordering always requires an explicit confirmed total.

License

MIT. Unofficial project, not affiliated with Yandex.

Available Tools

22 tools
active_ordersA

Currently tracked orders with status and ETA. Read-only.

Covers in-progress orders (Lavka's order-tracking feed); past orders are in order_history.

Inputs: no named parameters. Returns: object

add_to_cartA

Add a product to the cart (increments if already present). No charge.

product_id is the id from a search result. Pass price from the same search result when available (Lavka validates it on cart writes).

IMPORTANT: search can return items that are only stocked in «Большая Лавка» (a different store) — they add fine but can't be ordered from the current one. After adding, check the returned cart's warning and each item's unavailable_on_depot; drop any flagged item with update_cart_item(id, 0).

Inputs: product_id (required), price, quantity. Returns: object

cancel_orderB

Cancel an order by id (e.g. one returned by confirm_order/active_orders).

Inputs: order_id (required). Returns: object

checkout_previewA

Preview the order: items, delivery fee, ETA, address, payment, TOTAL.

Charges NOTHING. Show the returned total to the user and ask them to confirm it out loud before calling confirm_order. Always run this before confirming.

If the summary has a warning, or available_for_checkout is false, or any item has unavailable_on_depot: true, the order will be REFUSED — fix the cart (remove/replace those items) and preview again before confirming.

Inputs: no named parameters. Returns: object

clear_cartA

Remove everything from the cart. No charge.

Inputs: no named parameters. Returns: object

confirm_orderA

Place the order and CHARGE the card. Irreversible — real money.

Call ONLY after checkout_preview was run and the user explicitly said yes to the previewed total. Pass that exact total as confirmed_total. The order is refused unless: a preview was run recently, confirmed_total matches it, and — critically — the live cart still matches the previewed cart at submit time (same version and total). If anything drifted, nothing is charged and you must preview + confirm again.

Returns the order id and payment_status. "wait_user_action" means the bank requires 3-D Secure — give the user redirect_url to finish paying. cancel_order cancels.

Inputs: confirmed_total (required). Returns: object

get_category_groupA

List the categories inside one catalog group, by group id.

Group ids come from list_categories (each group carries an id). Read-only.

Inputs: group_id (required), layout_slug. Returns: object

get_category_productsA

List products in a catalog category. Read-only.

Get category_id from list_categories or get_category_group. Returns the category's subcategories (id, title, product_count) plus up to limit products sorted as Lavka shows them — raise the limit to page further using total_products. Each result's id works with add_to_cart and its slug with get_product.

Pass subcategory (an id or title from the result) to see only that shelf. group_id/layout_slug are only needed for non-grocery storefronts; without group_id the parent group is resolved via one extra lookup.

Inputs: category_id (required), limit, group_id, layout_slug, +1 more. Returns: object

get_orderA

Get full details of a specific order: items, totals, address, status, payment.

Pass an order_id from order_history or active_orders.

Inputs: order_id (required). Returns: object

get_productA

Get one product: price, size, stock, description, nutrition. Read-only.

product is an id or slug from a search result, or a Lavka link (a lavka.yandex.ru/good/... page or a shared ...?item= link).

nutrition is the КБЖУ block exactly as the product card shows it, numbers as Lavka gives them (nothing recomputed), or null when the card has none (non-food items):

  • per_100g: {kcal, protein, fat, carbs} per 100 g, or null.

  • per_portion: the same per the card's other tab, with its label ("Всё блюдо", "На упаковку", "На 50 г", ...), or null if the card has only one tab.

  • default_basis: the only tab ("per_100g" / "per_portion") when the card has one; null when it has both (Lavka doesn't say which one opens).

  • portion_grams: the portion's weight when the card states it (from the label, or the item's weight for a whole dish/pack), else null.

  • warning: null, or a note that per_portion doesn't follow from per_100g for that weight — Lavka's own data is wrong then; don't log it blindly.

Inputs: product (required). Returns: object

lavka_statusA

Show whether the Lavka session and delivery location are configured.

Read-only. Call this first to check setup before other tools.

Inputs: no named parameters. Returns: object

list_addressesA

List your saved Lavka delivery addresses (by name). Read-only.

Use a returned label with use_address to switch delivery to that place.

Inputs: no named parameters. Returns: object

list_categoriesA

Browse the Lavka catalog menu: category groups with their categories.

Returns every group (id, title) and its categories (id, title) — use a category id with get_category_products. layout_slug picks the storefront: "grocery" (default) is the main food catalog; hubs like "pharmacy" (Аптека) and "pet_store" (Зоотовары) have their own. Read-only.

Inputs: layout_slug. Returns: object

list_payment_methodsA

List the user's saved cards and which is the default. Read-only.

Use a returned id with set_payment_method to choose which card an order charges. By default the order uses the account default card.

Inputs: no named parameters. Returns: object

order_historyA

Get list of past orders. Read-only.

Use last_order_id from the last result for pagination (pass it as last_order_id to fetch the next page). Returns order id, status, total, items count, date.

Inputs: limit, last_order_id. Returns: object

search_productsA

Search the Lavka catalog at the current delivery location. Read-only.

Each result has an id (use it with add_to_cart) and a slug; get_product takes either.

Inputs: query (required), limit. Returns: object

set_delivery_addressB

Set delivery to ANY address by free text — works for a new city.

Resolves the address to coordinates + city/street/house via Lavka's own geo search. Example: set_delivery_address("Казань, улица Баумана, 1", flat="12").

Inputs: query (required), flat, comment, entrance. Returns: object

set_locationA

Set the delivery location (required before catalog/cart calls).

Provide either lat+lon coordinates or a saved address_id. Persists to config.

Inputs: lat, lon, label, address_id. Returns: object

set_payment_methodA

Choose which saved card orders will charge (persists). Pass an id from list_payment_methods. Pass an empty string to revert to the account default.

Inputs: card_id (required). Returns: object

update_cart_itemA

Set the exact quantity of a cart item. quantity=0 removes it. No charge.

Inputs: quantity (required), product_id (required). Returns: object

use_addressA

Switch delivery to one of your saved addresses, matched by name.

Catalog, cart and prices are location-scoped, so this re-points everything. A saved address carries city/street/house; pass flat/entrance/comment if the order needs them.

Inputs: name (required), flat, comment, entrance. Returns: object

view_cartA

Show the current cart contents and running total. Read-only.

The cart also reports order-readiness. Watch these:

  • warning: a plain-language problem to fix (or null). If set, act on it.

  • each item's unavailable_on_depot: true = it's in the cart but CANNOT be ordered from the current store (only in «Большая Лавка», or sold out here).

  • available_for_checkout: false = the order can't be placed as-is. Remove/replace flagged items with update_cart_item(product_id, 0) before checkout.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 22 tools

    Disambiguation4/5

    Most tools map to distinct resource+action pairs, but the location cluster (set_location, use_address, set_delivery_address) and the catalog cluster (list_categories vs get_category_group, which both surface categories by group) have overlapping purposes that could cause misselection. Descriptions do a good job clarifying the differences.

    Naming Consistency4/5

    The set is dominated by a predictable verb_noun pattern (get_product, list_categories, add_to_cart, set_payment_method, cancel_order), with a few noun-only outliers (active_orders, order_history, lavka_status, checkout_preview). Minor deviations, still clearly readable.

    Tool Count4/5

    22 tools is on the heavy side but justified by a genuinely broad domain spanning catalog browsing, cart, checkout, orders, payment, and addresses. Each tool earns a place, though the category-browsing tools could likely be consolidated.

    Completeness4/5

    The surface covers the full shopping lifecycle: discovery, cart mutation, preview, charge, cancel, order history, payment methods, and address/location setup. Minor gaps like deleting a saved address (only setting one exists) are workable around.

    Maintenance

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables natural-language interaction with the Yango Tech Retail B2B API to create and track orders, browse product catalogs, and manage prices, discounts, and stock levels across darkstores.
      16
      86 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search grocery products, manage shopping carts, retrieve account, order, delivery, and premium information, and get personalized meal suggestions and discounted items across multiple European grocery delivery platforms.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search grocery products, manage shopping carts, view orders and delivery information, and get personalized meal and deal suggestions across multiple European grocery delivery services.
      MIT