picnic-mcp
picnic-mcp lets an AI assistant shop Picnic groceries—searching products, managing a cart, and choosing delivery slots—without placing orders.
Search Picnic products using Dutch product queries and get product IDs.
View the cart, add products, remove products, and set quantities.
List available delivery slots and select one for the cart.
Get product details such as ingredients, allergens, nutrition, storage info, promotions, and price.
Find cheaper similar products by unit price (kg, litre, or piece).
List weekly promotions and frequently bought favorites by section or aisle.
If enabled, also view deliveries and work with recipes: search, save/unsave, view ingredients/steps, and add/remove recipe ingredients to/from the cart.
It cannot place an order and returns compact JSON without sensitive account details.
Allows interaction with the Picnic online supermarket, providing tools to search products, add and remove products from the shopping cart, and view the cart contents, quantities, prices, total, and delivery window. It cannot place orders.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@picnic-mcp search for lactose-free milk and add the best match to my cart"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
picnic-mcp
An MCP server for the online supermarket Picnic. It lets a model search Picnic's products, fill your shopping cart, pick a delivery slot, show promotions and the products you usually buy, and use recipes. It can't place an order.
Unofficial: not made or supported by Picnic. Built on picnic-api. Tested with Dutch accounts; German and French accounts should work, but haven't been tested.
Part of a set
picnic-api, picnic-web and picnic-mcp are developed and released together. When the Picnic app changes how it gets its data, picnic-api follows it and picnic-web and picnic-mcp are updated in the same change, so their latest versions always work together.
Project | What it is |
Node.js library for Picnic's API: products, cart, delivery slots, deliveries and recipes. | |
Web interface for Picnic, to shop from your browser. Live at picnic.maartenvandenhoven.com. | |
MCP server that lets AI assistants search products, fill your cart and pick a delivery slot. |
Related MCP server: aus-cart-mcp
Tools
The tools come in groups. cart, slots, product and discover are on by default; turn groups on or off with PICNIC_MCP_TOOLS (see Setup).
Group | Tool | What it does |
|
| Searches products. Returns a |
| Adds one or more products by their ids. Returns the quantity of each in the cart, the products that failed, the cart total, and replacements when a product can't be delivered. | |
| Sets how many of a product are in the cart; 0 removes it. | |
| Removes a product by its id. | |
| Shows the cart: products, quantities, prices, total and delivery window, and replacements for products that can't be delivered. | |
|
| Lists the delivery slots, two days at a time or for one date. |
| Chooses the delivery slot of the cart. | |
|
| Shows a product's ingredients, allergens, nutrition, storage info, promotion and price, with the price per kg, litre or piece. |
| Finds similar products that cost less per kg, litre or piece, cheapest first, with the saving per unit. | |
|
| Lists this week's promotions per section (e.g. per category), all promotions of a section, or the products of one promotion. |
| Lists the products you buy, per aisle, as the app's "Favorieten" tab does. For "add my usual groceries". | |
|
| Shows upcoming deliveries (window, number of products, total, and the expected arrival while the driver is on the way) or the last past ones. Optionally the products, e.g. to order the same again. |
|
| Searches Picnic's recipes. |
| Lists the recipes you saved in the app. | |
| Shows a recipe's ingredients, allergens and steps. The recipe tools also take a recipe link shared from the Picnic app. | |
| Adds a recipe's ingredients to the cart for a number of portions. | |
| Removes a recipe and its ingredients from the cart. | |
| Saves a recipe in the app. | |
| Removes a recipe from your saved recipes. |
Output is compact JSON with only what a model needs. It leaves out your name, address, payment details, order numbers and other account details. Keep in mind that whatever the tools return is sent to the model your MCP client uses.
When a search has no clear match and your MCP client can show a form (elicitation), you pick the product in the client yourself, instead of the model asking you in the chat.
Setup
Requires Node.js 20 or later.
1. Get an auth key
npx picnic-mcp loginIt asks for your country, email and password, and the code Picnic texts you when your account uses two-factor authentication. It prints an auth key and stores nothing. Keep the key secret: it gives access to your Picnic account.
2. Add the server to your MCP client
Claude Desktop and other MCPB clients: download picnic-mcp.mcpb from the latest release, open it, and fill in the auth key.
Other clients take a configuration like this:
{
"mcpServers": {
"picnic": {
"command": "npx",
"args": ["-y", "picnic-mcp"],
"env": {
"PICNIC_AUTH_KEY": "<your auth key>",
"PICNIC_COUNTRY_CODE": "NL"
}
}
}
}PICNIC_COUNTRY_CODE is NL, DE or FR (default NL). To choose the tool groups, add PICNIC_MCP_TOOLS with a comma-separated list, e.g. "cart,slots,product,discover,deliveries,recipes" (default cart,slots,product,discover). Fewer tools help smaller models pick the right one. The server runs over stdio; see HTTP to reach it over the network.
The server is also listed in the MCP Registry as io.github.MRVDH/picnic-mcp.
When the key expires, the tools say so; run npx picnic-mcp login again.
HTTP
picnic-mcp http serves the same tools over HTTP at /mcp, for clients that connect to a URL. It needs a token that clients send as Authorization: Bearer <token>; generate one with:
openssl rand -hex 32PICNIC_AUTH_KEY=<auth key> PICNIC_MCP_HTTP_TOKEN=<token> npx picnic-mcp httpVariable | |
| Required, at least 32 characters. Anyone with it can change your cart, so keep it secret. |
| Address to listen on. Default |
| Default |
| Host names allowed besides localhost, comma-separated, e.g. the name of a reverse proxy in front of it. Requests with another Host or Origin header are refused. |
The server doesn't do HTTPS. To use it from another machine, put it behind a reverse proxy with HTTPS, and add the proxy's host name to PICNIC_MCP_HTTP_ALLOWED_HOSTS.
Use it in your own code
createServer returns the MCP server without reading environment variables or files, so you can run it in your own process and connect it to any MCP transport:
import { createServer } from "picnic-mcp";
const server = createServer({ authKey: "<auth key>", countryCode: "NL" });
await server.connect(transport);Pass tools to choose the tool groups (e.g. tools: ["cart", "recipes"]), client instead of authKey to use a picnic-api client you already have, and onError to handle errors from Picnic yourself (by default they're logged to stderr).
Product images
Results that list products (search, the cart, added products, promotions, favorites, product details) carry the image URLs of those products in _meta["picnic-mcp/images"], by product id. MCP clients don't pass _meta to the model, so the images cost no tokens; your own code can use them, e.g. to show product photos. The images don't need the auth key. The key is exported as IMAGES_META_KEY.
Available Tools
11 toolsadd_to_cartAdd to cartA
Add one or more products to the user's Picnic shopping cart. Get the product ids from search_products first; put all products the user asked for in one call (at most 20). Returns each added product with the quantity now in the cart, the products that failed, and the cart total. A product that can't be delivered in the selected delivery window has unavailable and replacements: tell the user and offer them. To change how many of a product are in the cart ("make it 4"), use set_cart_quantity instead. This does not place an order.
Inputs: items (required).
get_cartGet cartARead-only
Show the user's Picnic shopping cart: the products with their quantity and price, the total, and the delivery window. A product that can't be delivered in that window has unavailable with the reason, and replacements Picnic offers instead.
Inputs: no named parameters.
get_cheaper_alternativesFind cheaper alternativesARead-only
Find cheaper versions of a Picnic product: similar products that cost less per kg, litre or piece, cheapest first. Use it when the user asks for a cheaper option or wants to save on a product. Get the product id from search_products or get_cart. It only reads; to swap a product in the cart, ask the user first.
Inputs: productId (required).
get_delivery_slotsGet delivery slotsARead-only
List the delivery slots the user can choose for the cart. Without a date it lists the first 2 days and the dates of the other days. Pass a date from that list to see its slots. Use select_delivery_slot once the user picked a slot.
Inputs: date.
get_favoritesGet favoritesARead-only
List the products the user buys at Picnic, per aisle, e.g. for "what do I usually buy?" or to offer products for "my usual groceries". Without input it lists the aisles with a few products each; pass an aisleId for all of the user's products in that aisle. Products have ids for add_to_cart; add only the ones the user asks for.
Inputs: aisleId.
get_productGet product detailsARead-only
Get the details of a Picnic product: ingredients, allergens, nutrition, storage info, promotion and price. Use it for questions such as whether a product contains gluten. Get the product id from search_products or get_cart.
Inputs: productId (required).
get_promotionsGet promotionsARead-only
List what is on promotion at Picnic this week. Without input it lists the sections (e.g. per category) with a few products and promotions each. Pass a section title for all products and promotions in it, or a promotionId for the products of one promotion. Products have ids for add_to_cart.
Inputs: section, promotionId.
remove_from_cartRemove from cartADestructive
Remove a product from the user's Picnic shopping cart. Get the product id from get_cart. Returns the quantity left in the cart and the cart total.
Inputs: productId (required), quantity.
search_productsSearch productsARead-only
Search the Picnic supermarket for a product and get its id for add_to_cart. Write the query in Dutch, as a short product name. The result has bestMatch when one product fits, usually one the user bought before: add that one. It has choices when there is no clear match: ask the user which one they want before adding anything. boughtBefore marks products the user ordered before.
Inputs: query (required).
select_delivery_slotSelect delivery slotAIdempotent
Choose when the cart is delivered. Only use a slotId from get_delivery_slots, after the user picked the slot. Returns the selected delivery window and the cart total. This does not place an order.
Inputs: slotId (required).
set_cart_quantitySet cart quantityADestructive
Set how many of a product are in the user's Picnic shopping cart, e.g. when the user says "make it 3". 0 removes the product. Get the product id from get_cart or search_products. Returns the quantity now in the cart and the cart total.
Inputs: quantity (required), productId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a clearly distinct resource+action target: search vs. detail (search_products/get_product), cart mutation varieties (add_to_cart, remove_from_cart, set_cart_quantity), delivery flows (get_delivery_slots/select_delivery_slot), and read-only discovery tools. The descriptions even explicitly disambiguate the tricky pairs, e.g. add_to_cart vs. set_cart_quantity for changing quantities.
All 11 tools use snake_case with a leading verb (get_, add_, remove_, set_, search_, select_), giving a predictable verb_noun or verb_preposition_noun pattern throughout. No mixed casing or vague standalone verbs.
11 tools is well-scoped for a grocery shopping assistant, with each tool mapping to a needed capability (search, product info, cart management, delivery, promotions, favorites, alternatives). No redundant or filler tools.
Covers discovery, product detail, full cart create/read/update/delete, delivery slot selection, promotions, and favorites—a thorough surface. The main gap is order placement/checkout (tools repeatedly note 'this does not place an order'), so an agent can build and schedule a cart but not finalize a purchase.
Maintenance
Related MCP Connectors
Product search for AI agents: Amazon + Shopify, cart-to-checkout buy path. Pay-per-call, no API key.
Product search for AI shopping agents: prices and buy links from big retailers. No key needed.
AI shopping gateway for product search, inventory, carts, and merchant-hosted checkout.
Live product search for AI agents across Shopify merchants and major retailers.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables searching Mercadona Online products and reading or carefully updating a user's cart via the Model Context Protocol from the command line or ChatGPT Web.6MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to search Australian retailers and fill the user's own online shopping cart through tools for product search, adding items, setting quantities, and checking connection and usage status. Supports Woolworths today, with Coles, Amazon Australia, Kmart and BIG W planned.1AGPL 3.0
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to search grocery products, manage shopping carts, and access account and order information across multiple online grocery platforms. It also supports smart shopping suggestions, deals, delivery slots, and order history.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to search grocery products, manage shopping carts, and retrieve account, order, delivery, and discount information across multiple European online grocery platforms.MIT