NZ Groceries MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 setupA 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 --exportPaste 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 |
| Resolve store names/areas to retailer-specific IDs |
| One page of live product results at a verified store |
| Current prices for up to 20 exact returned variant IDs |
| Receipt enrollment, freshness, coverage and limits; offline |
| Bounded receipt collection and progress |
| Saved receipt summaries and details |
| Historical paid prices with comparability rules |
| 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-dataReplace /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 shareTests 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search Coles, Woolworths and ALDI at once: prices, unit prices, specials, cheapest store per item.
Live prices, specials and unit prices from Coles, Woolworths, ALDI Australia and Woolworths NZ.
Danish grocery catalog as MCP tools: live offers across all major chains, stores, EAN lookup, stock.
Shopping MCP for AI agents: search, compare, Amazon buy links. Auto-register.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides grocery price and nutritional information search capabilities, allowing AI agents to search for food products, compare prices, and analyze nutritional content across different grocery stores.1-
- AlicenseNot gradedqualityNot gradedmaintenanceEnables 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.1MIT
- AlicenseAqualityBmaintenanceA 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.141MIT
- AlicenseAqualityBmaintenanceEnables browsing and searching the Woolworths New Zealand grocery catalogue, retrieving product details, checking specials, and managing a shopping trolley with optional account sign-in.184MIT