Voila Groceries MCP

io.github.dearlordylordPublished by GitHub account dearlordylordv0.3.0Updated Oct 24, 2026

Safe personal Voila grocery automation for search, slots, cart updates, and order history

VerifiedSTDIODesktop onlyProductivity & WorkflowBusiness & Commerce

Overview

AI-generated overview

Local stdio MCP server for personal Voila grocery shopping: product search, delivery slots, cart changes and order history, without checkout.

What you can do
  • Check session health and read the active shopping context (region, destination, delivery method, cart)
  • Search products, browse category products and scan discounted promotions
  • List delivery slots for a destination and reserve a chosen slot with explicit confirmation flags
  • Read the active cart, add or remove item quantities by product UUID, with notices for limited or repriced items
  • Read completed orders, single order details and aggregate previously ordered items
When to use it
For someone who shops at Voila and wants an assistant to help find products and discounts, compare delivery slots, adjust the cart, or review past orders, while keeping checkout and order placement out of the assistant's reach.
Requirements
Runs locally via npx (Node.js) over stdio. Authenticated use needs a session JSON file captured with the Voila CLI, passed as the absolute path in VOILA_AUTH_SESSION_PATH; no password goes in the config. VOILA_GUEST=1 forces guest mode. An optional read-only keepalive runs unless VOILA_KEEPALIVE=0.
Before you install
The session file at VOILA_AUTH_SESSION_PATH is a live account credential; keep it private and never expose it. Cart tools change real cart contents, and slot reservation acts on the account, though checkout and order placement are not exposed. It relies on the web app's internal endpoints rather than a documented API, so behavior may break. Do not expose the HTTP transport with a real session to the public internet.

Installation

In SourceWeft

  1. Open Voila Groceries MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Voila MCP

[npm] [npm downloads] [License: MIT] [MCP] [TypeScript] [Glama score]

Voila MCP is a Model Context Protocol server for safe personal Voila grocery automation. It exposes small, auditable tools for product search, category browsing, discounts, delivery slots, cart deltas, and completed order history without exposing checkout or order placement.

Published on npm as @firfi/voila-mcp. The repository also includes @firfi/voila-sdk and @firfi/voila-cli.

Packages

  • packages/voila-sdk: @firfi/voila-sdk, the TypeScript SDK for Voila sessions, search, categories, cart, order history, slots, and checkout-readiness helpers.
  • packages/voila-mcp: @firfi/voila-mcp, a stdio MCP server exposing small auditable tools.
  • packages/voila-cli: @firfi/voila-cli, a user CLI that reuses the MCP operation registry.

The root package is private. Publishable packages live under packages/.

MCP Setup

Voila does not publish a documented third-party customer API. This server uses the same same-origin JSON endpoints as the web app, so authenticated use is session-based. Capture a session interactively with the CLI; do not store a Voila password in MCP config.

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

If the session is missing, expired, or guest-only, tool results include authGuidance with the exact CLI login command to run. The MCP server itself does not launch a browser. A login performed while the server is running takes effect on its next tool call, without a restart.

With an explicit VOILA_AUTH_SESSION_PATH and guest mode off, the MCP server also runs a read-only authenticated-session keepalive. Set VOILA_KEEPALIVE=0 to disable it; VOILA_KEEPALIVE_INTERVAL_SECONDS defaults to 86400 seconds and must be at least 3600. The keepalive never bootstraps a guest and stops as misconfigured if its configured session snapshot disappears.

Tools

  • voila_check_session_health: report active, guest, expired, or retryable session state.
  • voila_get_active_shopping_context: read current region, destination, delivery method, and cart context.
  • voila_get_slot_listings: list delivery slots for an explicit destination and region.
  • voila_reserve_slot: reserve a caller-selected slot only with explicit confirmation flags.
  • voila_search_products: search products for the current session context.
  • voila_get_category_products: fetch products for a Voila category id.
  • voila_get_discounted_products: scan promotions and return meaningful discounted products.
  • voila_get_completed_orders: read completed orders with cursor pagination.
  • voila_get_order_details: read item-level details for one completed order.
  • voila_get_completed_order_items: aggregate previously ordered items across completed orders.
  • voila_get_cart: read active cart totals, limited items, unavailable data, and pricing notices.
  • voila_add_cart_items: add quantity deltas using Voila product UUIDs.
  • voila_remove_cart_items: remove quantity deltas using Voila product UUIDs.

The server does not expose checkout or order-placement tools. Cart mutations use quantity deltas and return server notices for limited, unavailable, and pricing-change cases.

Transports

Stdio is the default for local MCP clients:

bash
npx -y @firfi/voila-mcp

HTTP is available for registry inspection and deployments behind a trusted gateway:

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

The HTTP endpoint is /mcp unless MCP_HTTP_PATH is set. VOILA_GUEST=1 forces guest-session behavior for safe introspection environments such as Glama. Do not expose HTTP with a real session file directly to the public internet; put authentication and access control in front of /mcp.

CLI

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

The CLI default session path is ~/.config/voila/session.json. Browser login uses a persistent Playwright profile at ~/.cache/voila/browser-profile unless --profile is provided; log in manually and close the browser window to save.

Verification

bash
pnpm check-allpnpm package:audit

Live endpoint smoke tests remain opt-in. Do not run live cart mutation tests against a real account unless the test cleans up and the caller explicitly asks for it.

Source: README.md at commit 21c979d

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts