yandex-lavka-mcp is an unofficial MCP (Model Context Protocol) server that lets AI assistants order groceries from Yandex Lavka. It supports searching for products, building a cart, and placing real orders, and requires explicit human confirmation before any charge occurs.
[Purpose and Positioning] This project is aimed at users who want to use an AI assistant to operate their own Yandex Lavka account to complete shopping. It is an unofficial project; Yandex Lavka has no public API, so the project directly interfaces with the same private Web API used by lavka.yandex.ru and authenticates using the user's own Yandex session Cookie. The project states that it is not affiliated with or endorsed by Yandex, that use may violate Yandex's terms of service, and that the private API may change or be blocked at any time.
[Main Capabilities]
- Search the Yandex Lavka product catalog;
- Build a cart;
- Place an order and check out, using a two-step confirmation process to safeguard funds;
- Support multiple locations/cities (catalog, prices, and cart are all location-specific);
- Support switching to a saved address via use_address, or setting any address in any city via set_delivery_address (using Lavka's own address search for geocoding);
- Handle 3-D Secure: confirm_order submits the order and, after charging, polls the payment status; if the bank requires 3DS, it returns wait_user_action and redirect_url, and you need to open that link to complete payment;
- Provide cancel_order(order_id) to cancel an order.
[Fund Safety Mechanism] Placing an order is a deliberately two-step process: checkout_preview returns a complete summary and does not incur any charge; confirm_order(confirmed_total) will refuse to execute unless a preview has just been run and the passed total exactly matches the preview. Once the cart is changed, the preview becomes invalid and must be regenerated.
[Technical Composition and Installation/Usage] The tech stack is Python 3.12+, FastMCP, and httpx. The repository contains client.py (an asynchronous API client that handles session authentication, CSRF, request construction, and trimming oversized responses), endpoints.py (centrally stores all API paths, which can be overridden from configuration without changing code), server.py (the MCP tools visible to the assistant). The API is located at https://lavka.yandex.ru/api/v1/providers/（下单为 /api/v1/orders/submit), the request requires the CSRF token from the homepage HTML and the X-Lavka-Web- request headers, which the client already handles. The usage steps are roughly as follows: first log in to Lavka in the browser, and put the session cookie into ~/.config/yandex-lavka-mcp/config.json (on macOS it can be extracted directly from Chrome; on any system you can copy the Cookie request header from DevTools); then set the delivery location (copy config.example.json and edit it, or have the assistant set it via use_address / set_delivery_address; the catalog is unavailable when no location is set); finally register it with the assistant (such as mcpServers in Claude Desktop). By default it uses stdio, which is suitable for local clients; setting YANDEX_LAVKA_MCP_TRANSPORT=streamable-http exposes it over HTTP to support hosted instances and claude.ai custom connectors (mobile/web). The repository includes a prebuilt Dockerfile; secrets are injected at runtime and are not baked into the image.
[Remote Deployment and Authentication] A public endpoint will really spend money and must be protected. The custom connector UI in claude.ai only supports OAuth (it does not support static bearer or custom request headers; the latter applies only to Claude Code/Desktop). This server is a provider-agnostic OAuth 2.1 resource server and can connect to any OpenID-Connect provider (Zitadel, Keycloak, Auth0, Google, etc.), validating JWT access tokens according to that provider's JWKS and publishing via OAuth protected resource metadata. You need to install the server extra (pip install '.[server]'; the Docker image already includes it) and set the corresponding configuration. Unless OAuth is configured or YANDEX_LAVKA_MCP_ALLOW_INSECURE=1 is set to front it with your own authentication, an externally exposed HTTP transport will refuse to start.
[Captcha and Session Expiration] The session cookie will expire; when a call fails, you need to obtain it again and update YANDEX_LAVKA_MCP_CONFIG_JSON secret; there is no headless way to log in to Yandex. A hosted instance may be answered by Yandex with a captcha, which depends on the server IP rather than the session itself; in that case you need to solve a captcha once through that IP, and the script will output a spravka cookie; set it as the YANDEX_LAVKA_MCP_SPRAVKA secret and restart, and it is valid for about 30 days.
[Limitations and Notes] Lavka keeps only one cart per account on the server side, protected by the optimistic lock cartVersion. This server serializes its own cart writes and retries on version conflicts, so parallel tool calls within the same session are safe. But do not drive the same Yandex account from two places at the same time (for example, this server, a second MCP session, and the Lavka App); they all write to the same shared cart, and items from other writers will be mixed in. Use only one client at a time. Cookies and addresses are stored only in ~/.config/yandex-lavka-mcp/config.json (permissions 600, already git-ignored); never commit them. The server will not add payment methods or change account settings, and placing an order always requires an explicitly confirmed total. The project is under the MIT license and is provided "as is", without any warranty.
