yandex-lavka-mcp
An MCP server for ordering groceries from Yandex Lavka on your own account, with a mandatory preview-then-confirm step before any charge.
Setup & status —
lavka_statuschecks session/location;set_location(lat/lon or address_id),list_addresses,use_address(by saved name), andset_delivery_address(free-text, any city) point delivery anywhere.Browse the catalog —
search_products;get_product(by id, slug, or Lavka link, incl. КБЖУ nutrition);list_categories(with storefronts like grocery/pharmacy/pet_store);get_category_group;get_category_products(with subcategory filtering).Manage the cart —
view_cart(with order-readiness warnings),add_to_cart,update_cart_item(0 removes),clear_cart— no charges.Checkout —
checkout_previewreturns the full summary (items, fees, ETA, total) without charging;confirm_order(confirmed_total)places the real order and charges the card only if the preview matches.Payment —
list_payment_methodsandset_payment_methodto choose which saved card is charged.Orders —
cancel_order,active_orders,order_history(paged),get_orderfor full order details.Remote use — optional streamable-HTTP transport with OAuth-protected deployment for phone/web access.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yandex-lavka-mcp search for fresh milk"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
yandex-lavka-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.
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_orderspends 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 |
| — | Is the session + location set up? |
| — | Your saved Lavka addresses, by name. |
| — | Switch delivery to a saved address by name. |
| — | Set delivery to any address by text (any city). |
| — | Set delivery point by raw lat/lon. |
| — | Search the catalog at the current location. |
| — | Product detail by id, slug or Lavka link, incl. nutrition (КБЖУ per 100 g / per portion, as the card shows it). |
| — | Catalog menu: category groups with their categories (per storefront). |
| — | Categories inside one catalog group, by group id. |
| — | Products in a category + its subcategory shelf counts; optional subcategory filter. |
| — | Show cart + total. |
| — | Add an item. |
| — | Set exact quantity (0 removes). |
| — | Empty the cart. |
| no | Full summary: items, subtotal, discount, delivery, ETA, payment, total. |
| — | Your saved cards and which is the default. |
| — | Choose which card orders charge. |
| YES | Places the order and charges the default card (or the one set above). |
| — | Cancel an order by id. |
| — | Currently tracked orders with status/ETA. |
| — | Past orders (total, items count, date), paged. |
| — | 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 profileAny 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-mcpClaude 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 |
|
|
| Bind address for HTTP (default |
| The whole |
| 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 |
| Your provider's issuer URL (enables OAuth). |
| Public URL of this MCP server (the resource). |
| Expected token audience (optional but recommended). |
| Space-separated required scopes (optional). |
| Allow-list of token |
| 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_JSONsecret. 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:1080A 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]"
pytestOne 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 toolsactive_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 itslabel("Всё блюдо", "На упаковку", "На 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
Scored across 22 tools
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.
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.
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.
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
Related MCP Connectors
Search live store shelves, verify delivery windows, and run instant AI agent checkouts.
Russian APIs for AI agents: YooKassa, CDEK, Bitrix24 and more. Ready scenarios with code. No key.
AI-agent product catalog: search, lookup & purchase routing over verified merchant data.
Turn any shopping list into a ready-to-checkout grocery cart across 26 European supermarkets.
Related MCP Servers
- AlicenseAqualityDmaintenanceIntegrates with Yandex Market Partner API, providing search and execute tools for managing orders, returns, shipments, offers, prices, and other seller operations via natural language.181MIT
- AlicenseAqualityBmaintenanceEnables 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.1686 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables 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
- AlicenseNot gradedqualityAmaintenanceEnables 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