yandex-lavka-mcp

yandex-lavka-mcp

AI アシスタントが Yandex Lavka で食料品を注文できる MCP サーバーです。商品を検索し、カートを作成して実際に注文できます。料金が発生する前に、必ず人間による明示的な確認を行います。

警告

非公式です。 Yandex Lavka には公開 API がありません。このプロジェクトは、lavka.yandex.ru が使用するものと同じ非公開の Web API に、ご自身の Yandex セッション Cookie で認証して接続します。ご自身の買い物のために、ご自身のアカウントを自動操作します。

• Yandex とは提携しておらず、Yandex による承認も受けていません。使用すると Yandex の利用規約に違反する可能性があり、非公開 API はいつでも変更またはブロックされる可能性があります。
• confirm_order はカードで実際に支払いを行います。自己責任でご使用ください。
• 現状有姿で提供され、保証はありません（LICENSE を参照）。

できること

ツール	料金が発生するか	内容
lavka_status	—	セッションと場所が設定されているか確認します。
list_addresses	—	名前で保存済みの Lavka の住所を一覧表示します。
use_address	—	名前を指定して保存済みの住所に配送先を切り替えます。
set_delivery_address	—	テキストで任意の住所（どの都市でも可）を配送先に設定します。
set_location	—	緯度・経度を直接指定して配送先を設定します。
search_products	—	現在地のカタログで商品を検索します。
get_product	—	ID、スラッグ、または Lavka のリンクから商品詳細を取得します。栄養情報（カードに表示される 100 g あたり／1 食分あたりの КБЖУ）も含みます。
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	—	1 件の注文の全情報（商品、合計金額、住所、ステータス）を表示します。

支払いの安全性。 注文の確定は、意図的な 2 段階のフローになっています。checkout_preview は全明細を返しますが、料金は発生しません。confirm_order(confirmed_total) は、直前にプレビューが実行され、表示された合計金額と完全に一致する値が渡されない限り、注文を確定しません。カートを変更するとプレビューは無効になるため、再度プレビューする必要があります。

3-D Secure。 confirm_order は注文を送信して登録済みカードに請求した後、支払いステータスを確認します。銀行が 3-D Secure を要求する場合、payment_status は wait_user_action を返し、redirect_url が返されます。支払いを完了するには、この 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 を直接取得する（キーチェーンの確認で「許可」を 1 回選択）：

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

すべての OS — 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 全体を 1 つのシークレットとして指定します（ファイルの代わりに使用）。
YANDEX_LAVKA_MCP_SPRAVKA	Yandex が要求した場合に、サーバーの IP アドレスで CAPTCHA を通過するための値（CAPTCHA を参照）。

認証（任意の OIDC プロバイダー）

公開エンドポイントの利用には実際の費用がかかるため、必ず保護してください。claude.ai のカスタムコネクター UI がサポートするのは OAuth のみです（静的なベアラートークン／カスタムヘッダーには対応していません。これらは Claude Code/Desktop でのみ利用できます）。このサーバーはプロバイダーに依存しない OAuth 2.1 リソースサーバーです。任意の OpenID Connect プロバイダー（Zitadel、Keycloak、Auth0、Google など）を指定すると、そのプロバイダーの JWKS に対して JWT アクセストークンを検証し、OAuth 保護リソースメタデータを通じてそのプロバイダーを公開します。

server エクストラをインストールし（pip install '.[server]'。Docker イメージにはすでに含まれています）、次の項目を設定して有効にします。

変数	用途
YANDEX_LAVKA_MCP_OAUTH_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 の上書き（任意。指定しない場合は自動検出されます）。

ネットワークに公開される HTTP トランスポートは、OAuth が設定されていない場合、起動を拒否します（利用には実際の費用がかかります）。独自の認証で前段を保護している場合に限り、YANDEX_LAVKA_MCP_ALLOW_INSECURE=1 を設定してください。OAuth を設定しない場合でも、ループバック／ローカルでの利用は可能です。

セッション Cookie には有効期限があります。呼び出しが失敗するようになったら、Cookie を再取得して YANDEX_LAVKA_MCP_CONFIG_JSON シークレットを更新してください。ヘッドレスでの Yandex ログインには対応していません。 下記の CAPTCHA 認証は別のシークレットなので、この Cookie とは別に維持されます。

サーバーから CAPTCHA を解決する

Yandex はホスト型インスタンスに対し、CAPTCHA の表示を開始することがあります。判定基準はセッションではなくサーバーの 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

CAPTCHA のページを開いた状態で、使い捨ての Chrome ウィンドウが開きます。CAPTCHA を解決してください。スクリプトは spravka Cookie を標準出力に表示します。これを YANDEX_LAVKA_MCP_SPRAVKA シークレットとして設定し（そのままパイプで渡せます）、サーバーを再起動してください。有効期間は約 30 日です。CAPTCHA エラーが再発したら、もう一度実行してください。

開発

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

1 つのアカウントにつきカートは 1 つ

Lavka はアカウントごとにサーバー側のカートを 1 つ保持し、楽観的ロック用の cartVersion で管理しています。このサーバーは自身のカートへの書き込みを直列化し、バージョンの競合が起きた場合は再試行するため、1 つのセッション内でツールを並列に呼び出しても安全です。ただし、同じ Yandex アカウントを 2 か所から同時に操作しないでください（たとえば、このサーバーと別の MCP セッション、さらに Lavka アプリから同時に操作する場合など）。すべての操作で共有カートに書き込みが行われるため、別のクライアントが追加した商品が自分のカートに表示されます。一度に使用するクライアントは 1 つにしてください。

セキュリティとプライバシー

• Cookie と住所は ~/.config/yandex-lavka-mcp/config.json にのみ保存されます （chmod 600）。このファイルは Git の追跡対象外です。決してコミットしないでください。
• サーバーが支払い方法を追加したり、アカウント設定を変更したりすることはありません。
• 注文には必ず合計金額の明示的な確認が必要です。

ライセンス

MIT。Yandex とは提携していない非公式プロジェクトです。