Picnic

io.github.MRVDHPublished by GitHub account MRVDHv1.0.1Updated Nov 7, 2026

Search products, fill the cart and pick a delivery slot at the online supermarket Picnic

VerifiedSTDIODesktop onlyProductivity & WorkflowBusiness & Commerce

Overview

AI-generated overview

Unofficial MCP server for the Picnic online supermarket: lets an assistant search products, edit the shopping cart, pick a delivery slot and browse promotions.

What you can do
  • Search products and read product details such as ingredients, allergens, nutrition and price
  • View the cart, add products, change quantities and remove items
  • List delivery slots and select the slot for the cart
  • Browse this week's promotions and the products the user usually buys
  • With optional tool groups: list upcoming and past deliveries, and search, read, save or add recipes to the cart
When to use it
Useful when the user shops at Picnic and wants an assistant to build or adjust a grocery cart, check allergens or promotions, or choose a delivery window from chat. It cannot place an order, so it is a shopping helper rather than a checkout tool.
Requirements
Runs locally over stdio with Node.js 20 or later, via npx or the MCPB bundle. Needs a Picnic auth key in PICNIC_AUTH_KEY, obtained by running the login command with the account's country, email, password and two-factor code. PICNIC_COUNTRY_CODE is NL, DE or FR (default NL); PICNIC_MCP_TOOLS selects tool groups. An optional HTTP mode needs PICNIC_MCP_HTTP_TOKEN.
Before you install
PICNIC_AUTH_KEY grants access to the user's Picnic account and must be kept secret; it expires and must be regenerated. Tools change the real cart (add, set quantity, remove, select slot), though they cannot place an order. Tool output is sent to the model provider. The server is unofficial and untested with German and French accounts. HTTP mode has no HTTPS and anyone holding PICNIC_MCP_HTTP_TOKEN can change the cart.

Installation

In SourceWeft

  1. Open Picnic 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

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.

ProjectWhat it is
picnic-api [npm]Node.js library for Picnic's API: products, cart, delivery slots, deliveries and recipes.
picnic-webWeb interface for Picnic, to shop from your browser. Live at picnic.maartenvandenhoven.com.
picnic-mcp [npm]MCP server that lets AI assistants search products, fill your cart and pick a delivery slot.

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).

GroupToolWhat it does
cartsearch_productsSearches products. Returns a bestMatch when one product fits (usually one you bought before), or 2 or 3 choices to ask you about.
add_to_cartAdds 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.
set_cart_quantitySets how many of a product are in the cart; 0 removes it.
remove_from_cartRemoves a product by its id.
get_cartShows the cart: products, quantities, prices, total and delivery window, and replacements for products that can't be delivered.
slotsget_delivery_slotsLists the delivery slots, two days at a time or for one date.
select_delivery_slotChooses the delivery slot of the cart.
productget_productShows a product's ingredients, allergens, nutrition, storage info, promotion and price.
discoverget_promotionsLists this week's promotions per section (e.g. per category), all promotions of a section, or the products of one promotion.
get_favoritesLists the products you buy, per aisle, as the app's "Favorieten" tab does. For "add my usual groceries".
deliveriesget_deliveriesShows 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.
recipessearch_recipesSearches Picnic's recipes.
get_saved_recipesLists the recipes you saved in the app.
get_recipeShows a recipe's ingredients, allergens and steps. The recipe tools also take a recipe link shared from the Picnic app.
add_recipe_to_cartAdds a recipe's ingredients to the cart for a number of portions.
remove_recipe_from_cartRemoves a recipe and its ingredients from the cart.
save_recipeSaves a recipe in the app.
unsave_recipeRemoves 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

bash
npx picnic-mcp login

It 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:

json
{  "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:

bash
openssl rand -hex 32
bash
PICNIC_AUTH_KEY=<auth key> PICNIC_MCP_HTTP_TOKEN=<token> npx picnic-mcp http
Variable
PICNIC_MCP_HTTP_TOKENRequired, at least 32 characters. Anyone with it can change your cart, so keep it secret.
PICNIC_MCP_HTTP_HOSTAddress to listen on. Default 127.0.0.1, so only this machine can connect.
PICNIC_MCP_HTTP_PORTDefault 3000.
PICNIC_MCP_HTTP_ALLOWED_HOSTSHost 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:

ts
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.

Source: README.md at commit 92f91a8

Tools

10

search_products

Search products

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.

Parametersqueryrequired

get_cart

Get cart

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.

Takes no parameters.

add_to_cart

Add to cart

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.

Parametersitemsrequired

remove_from_cart

Remove from cart

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.

ParametersquantityproductIdrequired

set_cart_quantity

Set cart quantity

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.

ParametersquantityrequiredproductIdrequired

get_delivery_slots

Get delivery slots

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.

Parametersdate

select_delivery_slot

Select delivery slot

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.

ParametersslotIdrequired

get_product

Get product details

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.

ParametersproductIdrequired

get_promotions

Get promotions

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.

ParameterssectionpromotionId

get_favorites

Get favorites

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.

ParametersaisleId

Version history

2
  1. v1.0.1LatestNov 4, 2026
  2. v1.0.0Oct 23, 2026

Score

90% 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
  • 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 listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts