Voila Groceries MCP

Voila MCP

Voila MCP は、安全な個人向け Voila 食料品購入自動化のための Model Context Protocol サーバーです。商品検索、カテゴリーの閲覧、割引、配達枠、カートの増減、完了済み注文履歴に対応する、小規模で監査可能なツールを公開し、チェックアウトや注文の確定機能は公開しません。

npm では @firfi/voila-mcp として公開されています。このリポジトリには、@firfi/voila-sdk と @firfi/voila-cli も含まれています。

パッケージ

• packages/voila-sdk：@firfi/voila-sdk。Voila のセッション、検索、カテゴリー、カート、注文履歴、配達枠、チェックアウト準備状況の確認ヘルパーに対応する TypeScript SDK です。
• packages/voila-mcp：@firfi/voila-mcp。小規模で監査可能なツールを公開する stdio MCP サーバーです。
• packages/voila-cli：@firfi/voila-cli。MCP 操作レジストリを再利用するユーザー向け CLI です。

ルートパッケージは非公開です。公開可能なパッケージは packages/ の下にあります。

MCP のセットアップ

Voila は、ドキュメント化されたサードパーティー向け顧客 API を公開していません。このサーバーは Web アプリと同じオリジンの JSON エンドポイントを使用するため、認証を伴う利用はセッションベースです。CLI を使って対話形式でセッションを取得してください。Voila のパスワードを MCP 設定に保存しないでください。

{
  "mcpServers": {
    "voila": {
      "command": "npx",
      "args": ["-y", "@firfi/voila-mcp"],
      "env": {
        "VOILA_AUTH_SESSION_PATH": "/absolute/path/to/session.json"
      }
    }
  }
}

セッションがない場合、有効期限が切れている場合、またはゲスト専用の場合、ツールの結果には実行すべき正確な CLI ログインコマンドを含む authGuidance が含まれます。MCP サーバー自体はブラウザーを起動しません。サーバーの実行中にログインした場合、再起動しなくても次のツール呼び出しから反映されます。

明示的な VOILA_AUTH_SESSION_PATH を指定し、ゲストモードをオフにすると、MCP サーバーは認証済みセッションを読み取り専用で維持するキープアライブも実行します。無効にするには VOILA_KEEPALIVE=0 を設定してください。VOILA_KEEPALIVE_INTERVAL_SECONDS のデフォルトは 86400 秒で、3600 以上にする必要があります。キープアライブはゲストセッションを初期化せず、設定されたセッションスナップショットが見つからなくなると、設定ミスとして停止します。

ツール

• voila_check_session_health：アクティブ、ゲスト、有効期限切れ、再試行可能のいずれかのセッション状態を報告します。
• voila_get_active_shopping_context：現在の地域、配送先、配達方法、カートのコンテキストを読み取ります。
• voila_get_slot_listings：明示的に指定された配送先と地域の配達枠を一覧表示します。
• voila_reserve_slot：呼び出し元が選択した配達枠を、明示的な確認フラグがある場合にのみ予約します。
• voila_search_products：現在のセッションコンテキストに基づいて商品を検索します。
• voila_get_category_products：Voila のカテゴリー ID に対応する商品を取得します。
• voila_get_discounted_products：プロモーションを調べ、有意な割引商品を返します。
• voila_get_completed_orders：カーソルページネーションを使って完了済み注文を読み取ります。
• voila_get_order_details：完了済み注文 1 件の商品ごとの詳細を読み取ります。
• voila_get_completed_order_items：完了済み注文全体から、以前に注文した商品を集約します。
• voila_get_cart：有効なカートの合計、制限のある商品、入手できないデータ、価格に関する通知を読み取ります。
• voila_add_cart_items：Voila の商品 UUID を使って数量の増分を追加します。
• voila_remove_cart_items：Voila の商品 UUID を使って数量の増分を削除します。

サーバーはチェックアウトや注文確定のツールを公開しません。カートの変更には数量の増減を使用し、数量制限、入手不可、価格変更に関する通知をサーバーから返します。

トランスポート

ローカルの MCP クライアントでは、stdio がデフォルトです。

npx -y @firfi/voila-mcp

レジストリの確認や、信頼できるゲートウェイの背後へのデプロイには HTTP を利用できます。

MCP_TRANSPORT=http MCP_HTTP_HOST=0.0.0.0 PORT=8080 VOILA_GUEST=1 npx -y @firfi/voila-mcp

MCP_HTTP_PATH が設定されていない場合、HTTP エンドポイントは /mcp です。VOILA_GUEST=1 を設定すると、Glama などの安全なイントロスペクション環境でゲストセッションの動作が強制されます。実際のセッションファイルを使って HTTP をパブリックインターネットに直接公開しないでください。/mcp の前段に認証とアクセス制御を配置してください。

CLI

voila auth login --session ~/.config/voila/session.json
voila auth status --json
voila auth keepalive --interval 86400
voila search "milk"
voila orders list
voila orders details <order-id>
voila orders items --from-date 2026-06-01 --to-date 2026-06-30
voila cart get

CLI のデフォルトのセッションパスは ~/.config/voila/session.json です。ブラウザログインでは、--profile が指定されていない限り、永続的な Playwright プロファイル ~/.cache/voila/browser-profile が使用されます。手動でログインし、ブラウザーウィンドウを閉じて保存してください。

検証

pnpm check-all
pnpm package:audit

ライブエンドポイントのスモークテストは、引き続きオプトインです。テストで後処理が行われ、呼び出し元から明示的な依頼がない限り、実際のアカウントに対してライブのカート変更テストを実行しないでください。