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.
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_order spends real money on your card. Use at your own risk.
Provided as is, without warranty (see LICENSE).
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. |
| — | Show cart + total. |
| — | Add an item. |
| — | Set exact quantity (0 removes). |
| — | Empty the cart. |
| no | Full summary: items, subtotal, discount, delivery, ETA, payment, total. |
| YES | Places the order and charges the on-file card. |
| — | Cancel an order by id. |
| — | Currently tracked orders with status/ETA. |
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: Groceries MCP Server
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.
uv venv && uv pip install -e .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 returning "session expired".
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 "молоко"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"]
}
}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.)
Var | Purpose |
|
|
| Bind address for HTTP (default |
| The whole |
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.
uv pip install -e ".[dev]"
pytestLavka 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.
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.
MIT. Unofficial project, not affiliated with Yandex.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description fully discloses that the tool charges nothing (safe, read-only) and describes behavior for error cases (order will be refused and requires cart fixes). No side effects are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each serving a distinct purpose: purpose, cost clarification, usage flow, error handling. No redundancy or fluff; well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and the presence of an output schema, the description adequately covers what the preview contains and how to handle warnings. No missing context for a preview tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100% and description adds no parameter info. Baseline for 0 parameters is 4, and no additional semantics needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool previews the order including items, delivery fee, ETA, address, payment, and total. It is a specific verb-resource pair that distinguishes it from sibling tools focused on location, addresses, and products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to always run before confirming order, to show total to user and ask for confirmation, and details conditions (warning, available_for_checkout false, unavailable items) that require fixing the cart and re-previewing. Provides clear when-to-use and when-not-to-proceed guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details for one product: price, size, stock, description. Read-only.
Pass the slug from a search result.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the tool is 'Read-only', which is a key behavioral trait. With no annotations provided, this is adequate but lacks details on authentication, rate limits, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficiently written sentences with no wasted words, front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (presumably documenting return values), the description provides sufficient context for purpose, parameter usage, and safety. Minor gaps exist in behavioral details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'slug' parameter by noting it comes from a search result, compensating for the 0% schema description coverage. Could be more specific about slug format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get details'), resource ('one product'), and specific fields ('price, size, stock, description'), and distinguishes from sibling 'search_products' by specifying it retrieves a single product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to pass the 'slug' from a search result, providing clear usage context. Does not explicitly mention when not to use, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show whether the Lavka session and delivery location are configured.
Read-only. Call this first to check setup before other tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly marks the tool as read-only, which is key behavioral info. With no annotations, it carries the full burden, and it does this well. Could add more about error states, but the output schema likely covers return details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no wasted words. Essential info is delivered efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 0 parameters and an output schema, the description fully covers what the tool does, its read-only nature, and usage order. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description adds no parameter info because none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it shows whether the Lavka session and delivery location are configured. It uses a specific verb ('Show') and resource, and is distinct from sibling tools like set_location or search_products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to call this first before other tools to check setup, providing precise when-to-use guidance and suggesting a sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your saved Lavka delivery addresses (by name). Read-only.
Use a returned label with use_address to switch delivery to that place.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description declares 'Read-only', disclosing side-effect-free behavior. Additionally explains how returned label is used, enhancing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. Purpose and usage guidance are front-loaded and efficiently communicated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple list tool with output schema, the description fully covers what the tool does, its read-only nature, and how to use its output. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is effectively 100%. Description adds meaning beyond schema by noting addresses are listed by name, compensating for lack of params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists saved Lavka delivery addresses by name. Distinguishes from siblings by explicitly mentioning the returned label is used with use_address, showing differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Indicates when to use (to list addresses) and how to use the output (with use_address). Lacks explicit when-not-to-use but adequate for a simple read-only tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 (use it with
get_product).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
States 'Read-only' which is a key trait, and implies location dependency. With no annotations, description covers basic behavior but lacks details on error states, rate limits, or pagination behavior beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with two sentences, front-loaded with purpose and read-only nature. Every sentence adds value; no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists so return values are covered. Description ties results to other tools and states core behavior. Missing some details like limit behavior or error conditions, but overall adequate for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description does not mention any parameters (query, limit). No compensation for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'search', resource 'Lavka catalog', and scope 'at current delivery location'. Differentiates from siblings by linking results to other tools (add_to_cart, get_product) via id and slug.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes read-only and dependency on current delivery location. Provides hints on how results connect to other tools, but does not explicitly state when to use this tool versus alternatives like get_product.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the delivery location (required before catalog/cart calls).
Provide either lat+lon coordinates or a saved address_id. Persists to config.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | ||
| lon | No | ||
| label | No | ||
| address_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral transparency. It adds that the location persists to config, which is a useful behavioral trait. However, it does not disclose side effects (e.g., overriding previous location), authorization requirements, or rate limits. For a simple setter, this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences. The key purpose is front-loaded in the first sentence, and the second sentence adds parameter guidance. Every word is earned; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (4 optional parameters, simple setter) and the existence of an output schema, the description covers the main points: what it does, when to use it, and how to use it. It could mention error handling or output format, but the output schema likely covers returns. The description is nearly complete for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% parameter description coverage, so the description must compensate. It explains that lat+lon or address_id are alternative ways to provide the location, which adds semantic grouping. However, it does not explain the 'label' parameter, leaving its purpose unclear. The description partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and resource ('delivery location'), and clarifies it is a prerequisite for catalog/cart calls. It clearly states the action but does not explicitly differentiate from the sibling tool 'use_address', which might also set a location. The purpose is clear but lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that the tool is required before catalog/cart calls, providing a clear usage context. It also specifies the two ways to provide the location (lat+lon or address_id). However, it does not mention when not to use it or provide alternative tools, missing the full 'when/when-not/alternatives' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| flat | No | ||
| name | Yes | ||
| comment | No | ||
| entrance | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool re-points catalog, cart, and prices, and that a saved address carries city/street/house. It also notes optional flat/entrance/comment parameters. Without annotations, this provides adequate behavioral context, though it omits potential error states (e.g., name not found) or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a distinct purpose: purpose, effect, parameter details. No fluff, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (not shown), the description does not need to detail return values. It adequately covers the tool's functionality, parameters, and impact, and distinguishes from siblings. It is complete for a tool with 4 params and a clear use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning: 'matched by name' for required name, and 'pass flat/entrance/comment if the order needs them' for optional params. This clarifies their purpose beyond the schema's bare titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Switch delivery to one of your saved addresses, matched by name.' It specifies the verb ('switch') and resource ('delivery to a saved address'), and contrasts with sibling tools like list_addresses (listing) and set_location (likely setting a different location).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool: when you want to switch delivery to a saved address. It mentions that catalog, cart, and prices are location-scoped, implying the tool re-points everything. However, it does not explicitly state when not to use it or compare directly with siblings like set_location.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0checkout_previewget_productlavka_statuslist_addressessearch_productsset_locationuse_addressScored across 7 tools
Each tool has a clear and distinct purpose: status checking, location setting, address listing, address selection, product search, product details, and checkout preview. No two tools overlap in functionality.
Most tool names follow the verb_noun pattern in snake_case (set_location, list_addresses, use_address, search_products, get_product, checkout_preview). The exception is lavka_status, which is noun_noun, but overall the style is consistent.
With 7 tools, the server covers the core workflow of setting up a delivery location, managing addresses, searching products, and previewing checkout. The count feels appropriate for the domain.
The tool set lacks essential cart management tools such as add_to_cart, remove_from_cart, and a confirm_order tool (though implied by checkout_preview). Without these, the order flow cannot be completed through the MCP server, leaving a significant gap.
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.
AI shopping gateway for product search, inventory, carts, and merchant-hosted checkout.
Manage your NanoCart store from any AI agent: products, orders, coupons, subscribers, reports.
