Voila Groceries MCP

本地服务

github.com商业与营销010 周前更新

代码仓库访问官网

关于 Voila Groceries MCP

Voila Groceries MCP 是用于个人采购的 MCP 服务，支持商品与促销查询、配送时段、购物车调整和订单历史。工具便于审计，不提供结账或下单功能。

主要功能

01搜索商品和分类
02查找折扣商品
03查看并预留配送时段
04读取已完成订单历史
05查看并调整购物车数量

适用场景

01查找商品及当前折扣
02检查可用配送时段
03查看历史订单和所购商品
04调整购物车数量而不下单

MCP 相关

向 MCP 客户端提供会话状态、商品查询、配送时段、购物车操作和已完成订单等工具。不提供结账或下单工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "dearlordylord-voila": {
      "command": "npx",
      "args": [
        "-y",
        "@firfi/voila-mcp"
      ],
      "env": {
        "VOILA_GUEST": "<VOILA_GUEST>",
        "VOILA_AUTH_SESSION_PATH": "<VOILA_AUTH_SESSION_PATH>"
      }
    }
  }
}

启动命令npx -y @firfi/voila-mcp

需要配置的环境变量

VOILA_GUESTSet to 1 for guest-session behavior in registry inspection or unauthenticated discovery.

VOILA_AUTH_SESSION_PATH密钥Absolute path to a session JSON file captured with the Voila CLI for authenticated account workflows. Read and written as one path; guest sessions are never written to it.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@firfi/voila-mcp0.3.0stdio

工具

收录的工具列表 · 更新于 3 周前

此工具无需参数。

详细介绍

Voila MCP

Voila MCP 是一个用于安全管理个人 Voila 购物的模型上下文协议服务。它提供小巧、可审计的工具，用于搜索商品、浏览类别、查看折扣、配送时段、购物车变更和已完成订单历史记录，但不提供结账或下单功能。

已发布到 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 操作注册表的用户命令行工具。

根软件包为私有。可发布的软件包位于 packages/ 下。

MCP 配置

Voila 未发布有文档说明的第三方客户 API。此服务使用与 Web 应用相同的同源 JSON 端点，因此需通过会话进行身份验证。请使用 CLI 交互式捕获会话；不要在 MCP 配置中存储 Voila 密码。

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

如果会话缺失、已过期或仅限访客，工具结果会包含 authGuidance，其中提供需要运行的确切 CLI 登录命令。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：读取一笔已完成订单的商品级详情。
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。对于 Glama 等安全的内省环境，设置 VOILA_GUEST=1 可强制使用访客会话行为。请勿将使用真实会话文件的 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；请手动登录并关闭浏览器窗口以保存。