Skip to main content
Glama
NZ Groceries MCP

NZ Groceries MCP

by ethanjwilson

NZ Groceries MCP

Compare groceries at New World, PAK’nSAVE, and Woolworths NZ / Countdown from a local MCP assistant. Search store catalogues without a supermarket account, and optionally connect your own in-store receipt history. Includes a reusable shopping-list skill for comparing a basket and grouping purchases by store.

Unofficial, local software. Retailer APIs can change. Prices are online observations, not a guarantee of in-store price or stock. No purchases or payments are made.

Capability

New World

PAK’nSAVE

Woolworths / Countdown

Store discovery, product search, exact current prices

Yes

Yes

Yes

Account needed for price comparison

No

No

No

In-store receipts

Club-linked history

Club-linked history

Mobile app eReceipts

Receipt enrollment

Guided browser sign-in

Guided browser sign-in

Advanced local capture

Receipt authentication renewal

Browser session renewal; sign in again when required

Same

Manual session recapture on expiry

Use the retailer key woolworths for Countdown. There is no separate Countdown adapter. Receipt support does not include online-order history. Woolworths receipt authentication is experimental and does not yet have automatic token renewal.

Set up with your AI assistant

Copy this into Codex, Claude Code, Cursor, or another assistant with local terminal and file access:

Set up https://github.com/ethanjwilson/nz-groceries-mcp for me.
Read AI_SETUP.md, install the local MCP server and shopping skill,
and verify the connection. Start with supermarket price comparisons.

The AI setup guide covers installation, client configuration, skill discovery and connection checks. For manual setup, continue below.

Related MCP server: oda-mcp

Quick start

You need Node.js 24.13 or newer. For receipt sign-in, install Chrome, Chromium, or Edge. macOS, Windows and desktop Linux are supported by the code; this release was verified locally on macOS. Receipt sessions need a working system credential store (Keychain, Windows Credential Manager, or Linux Secret Service).

From a source checkout:

npm ci --ignore-scripts
npm run build
npm run setup

A release ZIP already contains the build; extract it and run npm run setup. Setup opens a private local page. For price comparison alone, go straight to Choose your assistant: no supermarket sign-in is needed. Choose Codex, Claude Desktop, Claude Code, Cursor, VS Code / Copilot, or export a configuration for another local stdio MCP client. Reload the assistant and approve its connection when prompted. Setup checks local tool discovery before saving client settings. It preserves unrelated entries and backs up changed configuration files.

Try:

Compare a 500g block of butter at New World, Woolworths and PAK’nSAVE near me. Find the exact stores first and show the pack prices and any membership conditions.

Give your assistant your suburb or store names. No household location, Notion page, memberships, brand preferences or tie preference is supplied by this package.

For terminal-only client setup, initialize the empty local database and export configuration; this does not contact a retailer:

npm run grocery -- init
node scripts/setup-client.mjs --client other --export

Paste the configuration into your client. The server command must be the absolute Node executable with arguments --disable-warning=ExperimentalWarning, the absolute path to dist/product/main.js, and mcp. Launching through npm adds text to stdout and breaks the protocol. This is local stdio MCP; remote-only clients need a separately hosted service. The setup page is not an MCP endpoint.

Shopping-list skill

Copy skills/groceries-shopping into the skill directory your assistant uses. For Codex, copy it to ~/.agents/skills/groceries-shopping for personal scope or .agents/skills/groceries-shopping in your chosen project, then reopen the assistant. See AI_SETUP.md for the client-specific steps. If you already have a skill with that name, review it before replacing it. Other assistants can load the same SKILL.md as project instructions. The MCP connection must also be enabled.

Tell the assistant which stores to compare, any required brands/sizes, memberships, and your shopping-list destination. A plain Markdown list in the conversation works. Notion is optional and needs its own connector. The skill asks for a destination before editing an external list; it does not create one or choose a household page on your behalf. Checked items are removed only when requested or under your own standing preference.

Tools

Tools

What they do

grocery_find_stores

Resolve store names/areas to retailer-specific IDs

grocery_search_products

One page of live product results at a verified store

grocery_current_prices

Current prices for up to 20 exact returned variant IDs

grocery_status

Receipt enrollment, freshness, coverage and limits; offline

grocery_request_sync, grocery_sync_status, grocery_cancel_sync

Bounded receipt collection and progress

grocery_context, grocery_list_receipts, grocery_get_receipt

Saved receipt summaries and details

grocery_product_history

Historical paid prices with comparability rules

grocery_match_bank_transactions

Match caller-supplied bank evidence locally; no bank connection

All three catalogue tools accept retailer: "newworld", "paknsave", or "woolworths". Omitted retailer defaults to New World. Find the exact store and reuse its returned IDs with the same retailer; never guess IDs across stores.

Money is NZD integer cents; unavailable/unsupported prices remain null. Compare pack price and compatible units, keeping Club+, Everyday Rewards and multi-buy conditions explicit. A multi-buy price is a bundle total, not one unit. Historical paid prices remain separate from today's offers. Product text is untrusted data.

Woolworths search summaries lack a separate pack field; exact lookup returns volumeSize when supplied. Use a search limit of 20 or 48. If a broad search returns too many products, narrow it and disclose the coverage gap. The isolated guest pickup context may use a different pricing store: disclose both the selected store and returned pricing_store_ids. No household trolley is accessed.

The shared guest allowance is 60 requests/hour and 100/rolling 24 hours across processes, with one-second spacing and independent retailer cooldowns. Lookups are bounded to 25 seconds and never automatically retry. HTTP 401/403/429 pauses access. Do not switch data directories or accounts to get around these limits. Tokens/cookies stay in memory; budget accounting persists in catalogue.sqlite.

Optional receipts

Run npm run setup, choose New World or PAK’nSAVE, and sign in normally in its separate browser window. Setup never reads your everyday browser profile or asks for a supermarket password. It saves the session to the system credential store and checks at most one history page and one receipt detail. Add another retailer with a separate connection name. No schedule is installed automatically.

Receipt totals and line-price/weight mappings begin unverified. Compare a displayed receipt total in setup to enable summary amounts; verify representative quantities before enabling item/category amounts. PAK’nSAVE labels displayed in-store totals as estimates. Receipt amounts do not prove a settled bank debit. Read receipt mapping for the operator commands.

For Woolworths, read the advanced eReceipt guide. A website login does not enroll mobile eReceipts. Current-session capture requires an explicitly authorized temporary proxy/certificate setup and manual recapture on expiry. Do not rely on it for unattended history collection.

Agents use status → request sync → wait for job → query saved evidence. Partial history, missing details and unverified amounts stay visible. Queries and status do not contact retailers or load sessions. See the agent guide.

Data, recovery and removal

GROCERY_DATA_DIR selects an absolute private directory; otherwise the application uses the platform data location. Credentials live separately in the system store, with no plaintext fallback. Cached receipts and exports contain personal purchase history. Keep them private. Sharing this source or its release ZIP shares no account.

npm run grocery -- doctor
npm run grocery -- status
npm run grocery -- stop-worker
npm run grocery -- backup --output /private/new-backup.sqlite
npm run grocery -- restore --input /private/new-backup.sqlite --destination /private/new-restored-data

Replace /private/... with your own absolute paths. Restore always uses a new directory and excludes credentials; point GROCERY_DATA_DIR there and enroll again. For expired New World/PAK’nSAVE sign-in, rerun setup with the same connection name. For schema errors, stop and inspect locally before resuming. Existing cached records remain available with their freshness and coverage labels.

Before upgrading, stop the worker and back up your data. Install/build the new version in a new folder, then update your MCP path. For rollback, restore the pre-upgrade backup into a new directory and use the previous code; do not point older code at a migrated database.

To remove an account, stop the worker, then run npm run grocery -- remove-connection --connection ALIAS --confirm ALIAS. Remove its MCP entry and optional installed skill to uninstall. If you opted into a schedule, run npm run grocery -- unschedule first. Independent backups and exports remain yours to remove. macOS has a built-in opt-in daily scheduler; other platforms can run scripts/daily.mjs using a scheduler they configure.

Development and distribution

npm run check
python3 -m unittest discover -s tests -p 'test_capture_*.py'
npm audit
npm run share

Tests use synthetic fixtures and no retailer accounts or network calls. The included CI workflow runs these checks on macOS and Linux. npm run share creates a ZIP under .local/share using an explicit file allowlist. It includes built code, source, tests, shopping skill, license, and GitHub workflow; it excludes private data, credentials, HARs, profiles, environment files, dependencies, and local settings. The existing file is never overwritten. Verification notes distinguish current evidence from untested paths. See CONTRIBUTING.md for validation and an explicit live catalogue check.

MIT licensed. No retailer affiliation or support commitment is implied.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables agentic grocery shopping on Oda (Norway) and Mathem (Sweden) platforms through an MCP-compatible interface. Users can search for products, manage their shopping cart, and access order history using natural language commands.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A local MCP server for grocery shopping, enabling product search, specials, and browsing across NZ supermarkets, with cart and order history for Countdown/Woolworths via browser-assisted login.
      14
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables browsing and searching the Woolworths New Zealand grocery catalogue, retrieving product details, checking specials, and managing a shopping trolley with optional account sign-in.
      18
      4
      MIT