yandex-lavka-mcp

yandex-lavka-mcp

一个 MCP 服务，可让 AI 助手从 Yandex Lavka 订购食品杂货——搜索商品、构建购物车并下达真实订单——且在扣款前必须经过人工明确确认。

警告

非官方。 Yandex Lavka 没有公开 API。本项目使用与 lavka.yandex.ru 相同的私有 Web API，并通过你自己的 Yandex 会话 Cookie 进行身份验证。它只会自动操作你自己的账户，供你自己购物。

• 本项目与 Yandex 无关联，也未获得其认可。使用本项目可能违反 Yandex 的服务条款，私有 API 也可能随时更改或被封锁。
• confirm_order 会从你的银行卡中扣除真实款项。使用风险自负。
• 本项目按现状提供，不提供任何保证（参见 LICENSE）。

功能

工具	是否扣款？	功能说明
lavka_status	—	会话和位置是否已设置？
list_addresses	—	按名称列出你保存的 Lavka 地址。
use_address	—	按名称切换到已保存的配送地址。
set_delivery_address	—	通过文本设置任意地址作为配送地址（任何城市均可）。
set_location	—	通过原始纬度/经度设置配送地点。
search_products	—	搜索当前位置的商品目录。
get_product	—	按 ID、slug 或 Lavka 链接查询商品详情，包括营养信息（每 100 g / 每份的 КБЖУ，以商品卡片显示为准）。
list_categories	—	商品目录菜单：列出分类组及其分类（按门店分别列出）。
get_category_group	—	按分类组 ID 列出该目录组中的分类。
get_category_products	—	列出某个分类中的商品及其子分类货架数量；可选按子分类筛选。
view_cart	—	显示购物车和总额。
add_to_cart	—	添加商品。
update_cart_item	—	设置确切数量（设为 0 可移除）。
clear_cart	—	清空购物车。
checkout_preview	否	完整摘要：商品、商品小计、折扣、配送费、预计送达时间、付款方式和总额。
list_payment_methods	—	列出你保存的银行卡及默认卡。
set_payment_method	—	选择订单扣款所用的银行卡。
confirm_order	是	下单并从默认银行卡（或上方设置的银行卡）扣款。
cancel_order	—	按 ID 取消订单。
active_orders	—	当前跟踪的订单及其状态/预计送达时间。
order_history	—	分页列出历史订单（总额、商品数量、日期）。
get_order	—	查看单个订单的完整信息：商品、总额、地址和状态。

资金安全。 下单需有意执行两步操作：checkout_preview 会返回完整摘要且不扣款；confirm_order(confirmed_total) 只有在刚刚运行过预览，并且你传回预览显示的确切总额时才会继续。更改购物车会使预览失效，你必须重新预览。

3-D Secure。 confirm_order 会提交订单并从已登记的银行卡扣款，然后轮询付款状态。如果你的银行要求进行 3-D Secure 验证，payment_status 会返回 wait_user_action，并提供 redirect_url——打开该链接以完成付款（无头扣款无法完成 3DS）。cancel_order(order_id) 可取消订单。

多个地点 / 城市。 商品目录、价格和购物车均按地点区分。use_address("Дача") 可切换到已保存的地址；set_delivery_address("Казань, улица Баумана, 1", flat="12") 可用于任何城市中的任意地址（它通过 Lavka 自带的地址搜索进行地理编码）。

构建方式

• Python 3.12+ · FastMCP · httpx。
• client.py — 异步 API 客户端（会话身份验证、CSRF、请求构建、精简超大负载）。
• endpoints.py — 集中管理所有 API 路径（可通过配置覆盖，无需更改代码）。
• server.py — 助手可见的 MCP 工具。

API 位于 https://lavka.yandex.ru/api/v1/providers/* 下（以及用于提交订单的 /api/v1/orders/submit）。请求需要从首页 HTML 获取 CSRF 令牌，以及 X-Lavka-Web-* 标头——客户端会处理这些内容。

设置

1. 安装

uv venv && uv pip install -e .

2. 提供 Yandex 会话（一次性操作）

先在浏览器中登录 Lavka，然后将会话 Cookie 放入 ~/.config/yandex-lavka-mcp/config.json。

macOS — 直接从 Chrome 提取 Cookie（弹出一次钥匙串提示 → 点击“允许”）：

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

任何操作系统 — 从 DevTools 复制 Cookie 标头（Network → 任意 lavka.yandex.ru 请求 → Request Headers → Cookie）：

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

会话 Cookie 会过期——当调用开始因“Lavka session is not authorized”而失败时，请重新运行。

3. 设置配送地点

将 config.example.json 复制到 ~/.config/yandex-lavka-mcp/config.json 并编辑， 或通过助手使用 use_address / set_delivery_address 设置。只有设置地点后， 商品目录才能正常使用。运行冒烟测试：

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

4. 在助手中注册

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"]
  }
}

远程部署（通过手机下单）

默认情况下，服务使用 stdio（本地客户端）。设置 YANDEX_LAVKA_MCP_TRANSPORT=streamable-http，即可通过 HTTP 暴露服务，让托管实例为 claude.ai 自定义连接器 （手机 / 网页）提供支持。

项目附带预构建的 Dockerfile。密钥在运行时注入——绝不会写入镜像：

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

（镜像默认使用 stdio；上述 TRANSPORT 环境变量会将其切换为 HTTP。）

环境变量

变量	用途
YANDEX_LAVKA_MCP_TRANSPORT	stdio（默认）或 streamable-http。
YANDEX_LAVKA_MCP_HOST / _PORT	HTTP 绑定地址（Docker 中默认为 0.0.0.0:8000）。
YANDEX_LAVKA_MCP_CONFIG_JSON	将整个 config.json 作为一个密钥提供（而不是使用文件）。
YANDEX_LAVKA_MCP_SPRAVKA	服务器 IP 的验证码通行码（如果 Yandex 要求；参见验证码）。

身份验证（任意 OIDC 提供商）

公开端点会产生实际费用，因此请务必保护它。claude.ai 的自定义连接器界面仅支持 OAuth（不支持静态 bearer／自定义标头——这些仅适用于 Claude Code/Desktop）。本服务是与提供商无关的 OAuth 2.1 资源服务：将它指向任意 OpenID Connect 提供商（Zitadel、Keycloak、Auth0、Google 等），它便会根据该提供商的 JWKS 验证 JWT 访问令牌，并通过 OAuth 受保护资源元数据公布相关信息。

安装 server extra（pip install '.[server]'，Docker 镜像中已包含）并设置以下变量即可启用：

变量	用途
YANDEX_LAVKA_MCP_OAUTH_ISSUER	提供商的 issuer URL（启用 OAuth）。
YANDEX_LAVKA_MCP_SERVER_URL	此 MCP 服务的公开 URL（资源）。
YANDEX_LAVKA_MCP_OAUTH_AUDIENCE	预期的令牌受众（可选，但建议设置）。
YANDEX_LAVKA_MCP_OAUTH_SCOPES	以空格分隔的必需作用域（可选）。
YANDEX_LAVKA_MCP_OAUTH_SUBJECTS	允许调用此服务的令牌 sub 白名单（可选；限制最严格——每个请求都会使用你的 Lavka 会话）。
YANDEX_LAVKA_MCP_OAUTH_JWKS_URL	覆盖 JWKS URL（可选；否则会自动发现）。

除非配置了 OAuth，否则面向网络的 HTTP 传输拒绝启动（它会产生实际费用）。仅当你使用自己的身份验证机制为其提供保护时，才设置 YANDEX_LAVKA_MCP_ALLOW_INSECURE=1。在回环／本地环境中可以不设置 OAuth。

会话 Cookie 会过期；调用开始失败时，请重新捕获 Cookie 并更新 YANDEX_LAVKA_MCP_CONFIG_JSON 密钥。Yandex 不支持无头登录。 通过验证码后获得的凭据（见下文）是单独的密钥，因此不会受影响。

在服务器上处理验证码

Yandex 可能会开始向托管实例返回验证码——这由服务器的 IP 决定，而非会话（相同的 Cookie 在家中仍可使用）。此时工具会报错 "Yandex anti-bot returned a captcha"。通过该 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

系统会打开一个临时 Chrome 窗口，显示验证码；请完成验证。脚本会将 spravka Cookie 输出到 stdout——将它设为 YANDEX_LAVKA_MCP_SPRAVKA 密钥（直接通过管道传入）并重启。该 Cookie 有效期约为 30 天；验证码错误再次出现时，请重新操作。

开发

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

一个账户 = 一个购物车

Lavka 为每个账户保留一个由乐观锁 cartVersion 保护的服务端购物车。此服务会串行处理自己的购物车写入，并在版本冲突时重试，因此同一会话中的并行工具调用是安全的。但不要同时通过两个地方操作同一个 Yandex 账户（例如，此服务、第二个 MCP 会话以及 Lavka 应用）：它们都会写入同一个共享购物车，你会看到购物车中出现其他写入方添加的商品。一次只使用一个客户端。

安全与隐私

• Cookie 和地址仅保存在 ~/.config/yandex-lavka-mcp/config.json （chmod 600）中，并已加入 git 忽略列表。切勿提交它们。
• 服务绝不会添加付款方式或更改账户设置。
• 下单始终需要明确确认总金额。

许可证

MIT。这是非官方项目，与 Yandex 无关。