pepesto-mcp

# Pepesto MCP Server <!-- mcp-name: io.github.pepesto-solutions/pepesto-mcp --> MCP server for the [Pepesto API](https://www.pepesto.com/ai-grocery-shopping-agent/) — give your agent the ability to turn any recipe (a URL, plain text, or a photo) into a matched basket of real supermarket products with live prices, across 26 European supermarkets. The MCP covers the **recipe → matched cart** half of the workflow (parse / search / map ingredients to SKUs / check catalogs); placing the actual order is a separate step — see [Where checkout actually happens](#where-checkout-actually-happens). ## Quick install ### Claude Desktop Add to `claude_desktop_config.json`: ```json { "mcpServers": { "pepesto": { "command": "npx", "args": ["-y", "@pepesto/pepesto-mcp"], "env": { "PEPESTO_API_KEY": "pep_sk_…" } } } } ``` ### Claude Code ```bash claude mcp add pepesto -e PEPESTO_API_KEY=pep_sk_… -- npx -y @pepesto/pepesto-mcp ``` ## Getting an API key > Most tools need a key, but `pepesto_predirect` is **public and free** — it works with no key at all (the end user pays when they check out in the app). 1. Start with a pay-as-you-go credit pack — see <https://www.pepesto.com/pricing/>. 2. Mint an API key by calling `/link` with the email you used at checkout. The key is returned **only once** — store it immediately. ```bash curl -X POST https://s.pepesto.com/api/link \ -H "Content-Type: application/json" \ -d '{"email":"you@example.com"}' ``` 3. Set the key in your environment: ```bash export PEPESTO_API_KEY=pep_sk_… ``` ## Tools | Tool | Endpoint | Description | | --- | --- | --- | | `pepesto_oneshot` | `POST /oneshot` | One-shot recipe → matched cart, including a `redirect_url` for checkout. | | `pepesto_predirect` | `POST /predirect` | **Free, no API key.** Shopping list → deferred deep link (`redirect_url`); the **end user** pays when they check out in the Pepesto app. | | `pepesto_parse` | `POST /parse` | Parse a URL/text/image recipe into structured ingredients + `KgToken`. | | `pepesto_suggest` | `POST /suggest` | Search Pepesto's 1M+ recipe graph. | | `pepesto_products` | `POST /products` | Map `KgToken`s + supermarket to concrete products with prices. | | `pepesto_catalog` | `POST /catalog` | Full SKU dump for a supermarket. Only when explicitly requested; cache results. | | `pepesto_credits` | `POST /credits` | Check remaining credits. Free. | The MCP stops at "matched cart with prices" — see [Where checkout actually happens](#where-checkout-actually-happens) for how users finish the order. `/session`, `/checkout`, and `/link` are intentionally not wrapped; see [Roadmap](#roadmap) for what's planned. ## Example conversations ### Quick: recipe URL → matched cart The fastest path. One tool call returns a matched cart and a checkout link. > **User:** Use the BBC Good Food pizza margherita recipe to build a Tesco cart, and also add sparkling water and olive oil. > > **Assistant:** *[Uses `pepesto_oneshot` with `content_urls`, `content_text`, `supermarket_domain: "tesco.com"`]* > > **Assistant:** Cart matched at Tesco. Checkout link: `<redirect_url>`. ### Free, deferred handoff → end user pays (`pepesto_predirect`) When the API client doesn't want to pay for matching and a deferred deep link is acceptable. `pepesto_predirect` is **free** and needs **no API key**: it returns instantly with a link, and parsing + product matching happen lazily once the user opens it. The **user** is charged when they proceed to checkout in the Pepesto app (if the app isn't installed, they're sent to the app store first and the list is preserved). > **Who this is for:** `pepesto_predirect` is an **end-user / agent-facing** tool, not a developer-integration endpoint. It's the right fit when a person is chatting with an assistant (Claude Desktop, ChatGPT, etc.) and wants to hand their shopping list off to their own phone — the agent returns a link, the user finishes (and pays) in the app. If you're a developer building a product *on top of* Pepesto, you'll usually want `pepesto_oneshot` (matched cart up front, you pay) instead. Got a developer use case for `predirect` anyway? [Tell us](https://www.pepesto.com/contact) — we'd love to hear it. Use `pepesto_predirect` when the cost should fall on the end user; use `pepesto_oneshot` when the client wants the basket matched up front (with prices) and is willing to pay for it. > **User:** Here's my weekly shopping list — just give me a link I can open on my phone to finish in the Pepesto app. > > **Assistant:** *[Uses `pepesto_predirect` with `shopping_list: "2 avocados\n1 loaf of bread\n500 g tomatoes\n..."`]* > > **Assistant:** Done — **[🛒 Open your shopping list in Pepesto →](…)** > Free to open · 3 items ready · you only pay at checkout in the app. Open it on your phone (on a computer it'll show a QR code to scan). The tool returns this as ready-to-show Markdown — one tappable, labeled link plus a short caption — so the long `redirect_url` is never dumped as raw text. ### Browse the recipe graph → pick → matched cart For "find me something to cook" prompts, where the agent searches Pepesto's recipe graph first and returns matched products with prices. > **User:** Find me a vegan pasta recipe for two. > > **Assistant:** *[Uses `pepesto_suggest` with `query: "vegan pasta dinner for two"`]* > > **Assistant:** Three options: *Creamy Cashew Penne*, *Lemon Garlic Spaghetti*, *Roasted Veg Rigatoni*. Which would you like? > > **User:** Go with the first one. Shop it at Coop (coop.ch). > > **Assistant:** *[Uses `pepesto_products` with the chosen recipe's `kg_token` and `supermarket_domain: "coop.ch"`]* > > **Assistant:** Matched 8 ingredients at Coop — cashews CHF 4.20, penne CHF 1.95, ... — total CHF 18.40. ### Parse a specific recipe → matched cart When the user already has a recipe URL or text in mind. The MCP returns the matched product list — what to do with it is up to you. > **User:** Parse this and break out the ingredients: https://www.bbcgoodfood.com/recipes/pizza-margherita-4-easy-steps > > **Assistant:** *[Uses `pepesto_parse` with `recipe_url`]* > > **Assistant:** *Pizza Margherita in 4 easy steps* — 8 ingredients: strong bread flour, fast-action yeast, ... > > **User:** Now match those to Sainsbury's products. > > **Assistant:** *[Uses `pepesto_products` with the returned `kg_token` and `supermarket_domain: "sainsburys.co.uk"`]* > > **Assistant:** Matched 8 ingredients at Sainsbury's — total £6.40. ### Weekly meal plan → one merged matched cart Multiple `kg_token`s through `pepesto_products` in a single call — Pepesto merges duplicated ingredients across recipes. > **User:** Plan 5 keto dinners for the week and match them at Delhaize. > > **Assistant:** *[Uses `pepesto_suggest` with `query: "keto dinner low carb high protein", num_to_fetch: 5`]* > > **Assistant:** Five dinners: *Steak & Kale*, *Salmon Avocado Bowl*, *Zucchini Lasagna*, *Cauliflower Risotto*, *Chicken Caesar*. > > **User:** Build one shopping list that covers the whole week. > > **Assistant:** *[Uses `pepesto_products` with all five `kg_tokens` and `supermarket_domain: "delhaize.be"`]* > > **Assistant:** Combined match: 24 unique ingredients (some shared across recipes), estimated total €68.40 at Delhaize. ### Compare prices across two supermarkets Run the same recipe through `pepesto_products` for each market and compare totals. > **User:** Parse this Sunday lunch recipe. > > **Assistant:** *[Uses `pepesto_parse`]* > > **Assistant:** Got it: *Italian Sunday Lunch*, 12 ingredients. > > **User:** Show me the cart at both Esselunga and Conad so I can compare. > > **Assistant:** *[Uses `pepesto_products` twice — `supermarket_domain: "spesaonline.esselunga.it"`, then `supermarket_domain: "spesaonline.conad.it"`]* > > **Assistant:** Esselunga: €34.20. Conad: €31.50. Conad is €2.70 cheaper, mostly on pasta and tomatoes. ### Catalog dump for market analysis Only on explicit request, and cache aggressively — see [Pricing & best practices](#pricing--best-practices) below. > **User:** I'm building a price-comparison dashboard. Pull the full Plus NL catalog. > > **Assistant:** Heads up — `pepesto_catalog` is the most expensive call here. I'll only run it once; you should cache the result for at least a day. Confirm? > > **User:** Yes. > > **Assistant:** *[Uses `pepesto_catalog` with `supermarket_domain: "plus.nl"`]* > > **Assistant:** Catalog dumped: 1,847 SKUs across 23 categories. ## Supported supermarkets | # | Country | Supermarket | Domain / ID | | --- | --- | --- | --- | | 2 | 🇬🇧 GB | Sainsbury's | sainsburys.co.uk | | 3 | 🇬🇧 GB | ASDA | asda.com | | 4 | 🇬🇧 GB | Morrisons | groceries.morrisons.com | | 5 | 🇬🇧 GB | Waitrose | waitrose.com | | 1 | 🇬🇧 GB | Tesco | tesco.com | | 6 | 🇳🇱 NL | Albert Heijn | ah.nl | | 7 | 🇳🇱 NL | Jumbo | jumbo.com | | 8 | 🇳🇱 NL | Plus NL | plus.nl | | 9 | 🇩🇪 DE | Rewe | shop.rewe.de | | 10 | 🇨🇭 CH | Coop CH | coop.ch | | 11 | 🇨🇭 CH | Migros | migros.ch | | 12 | 🇨🇭 CH | Farmy | farmy.ch | | 13 | 🇨🇭 CH | Aldi CH | aldi-now.ch | | 14 | 🇧🇪 BE | Colruyt | colruyt.be | | 15 | 🇧🇪 BE | Delhaize | delhaize.be | | 16 | 🇮🇪 IE | Tesco IE | tesco.ie | | 17 | 🇮🇪 IE | SuperValu | shop.supervalu.ie | | 18 | 🇮🇪 IE | Dunnes | dunnesstoresgrocery.com | | 19 | 🇮🇹 IT | Esselunga | spesaonline.esselunga.it | | 20 | 🇮🇹 IT | Conad | spesaonline.conad.it | | 21 | 🇩🇰 DK | Nemlig | nemlig.com | | 22 | 🇳🇴 NO | Meny | meny.no | | 23 | 🇵🇱 PL | Frisco | frisco.pl | | 24 | 🇵🇱 PL | Auchan PL | zakupy.auchan.pl | | 25 | 🇧🇬 BG | Bulmag | bulmag.org | | 26 | 🇧🇬 BG | eBag | ebag.bg | Need a supermarket that isn't on this list? [Contact Pepesto](https://www.pepesto.com/contact). ## Where checkout actually happens This MCP stops at "matched cart with prices." It does **not** automate placing the order on the supermarket's website. Two ways to finish the trip: - **Pepesto app (recommended).** Open the `redirect_url` returned by `pepesto_oneshot` in a browser, or hand the user the matched-product list from `pepesto_products` and tell them to recreate it in the [Pepesto app](https://www.pepesto.com/) — that's where the hosted checkout flow lives, including login, basket review, and (for some markets) payment. - **The supermarket's own site.** The user can take the matched product list from `pepesto_products` and add the SKUs directly on tesco.com / coop.ch / etc. Slower, but no Pepesto account needed. ## Pricing & best practices Pepesto runs on simple pay-as-you-go credits — you only pay for what your agents actually use, and **credits never expire**, so a top-up is yours until you spend it. We also offer discounts for students and early-stage teams, so [say hi](https://www.pepesto.com/contact) if that sounds like you. Full per-call pricing and volume tiers live at <https://www.pepesto.com/pricing/>. A few tips to get the most out of every credit: - `pepesto_credits` is free — call it any time for a quick balance read-out. - `pepesto_predirect` is free and needs no API key — it defers matching and bills the **end user** at checkout, so it costs the API client nothing. - `pepesto_oneshot`, `pepesto_parse`, `pepesto_suggest`, and `pepesto_products` are the everyday calls (match a recipe, plan a week, compare baskets) and are priced for routine agent use. - `pepesto_catalog` does a full SKU dump for a supermarket and is the heaviest call. It's the right tool for genuine market analysis or price-comparison dashboards — just **cache the result** for at least a day per supermarket. Not sure you need it? [Tell us about your use case](https://www.pepesto.com/contact) and we'll usually point you to a cheaper path. ## Roadmap Planned to follow: - **`pepesto_session`** — wrap `/session` so an agent can build a Pepesto-side checkout session from selected SKUs. - **`pepesto_checkout`** — wrap `/checkout`, the turn-by-turn browser-automation loop that drives the supermarket's own site (login, add-to-basket, prompt-for-CAPTCHA, etc.). This is the missing piece for fully autonomous shopping. - **Hosted-checkout handoff** — surface the Pepesto-app deep link as a structured tool result (instead of free text), so MCP clients can render it as a button instead of a URL. If any of these would unblock you, [tell us](https://www.pepesto.com/contact) — it'll move them up the queue. ## Development ```bash git clone https://github.com/pepesto-solutions/pepesto-mcp.git cd pepesto-mcp npm install npm run build npm test npm run test:coverage ``` Run the inspector against the local build: ```bash PEPESTO_API_KEY=pep_sk_… npm run inspector ``` ## License The Pepesto MCP server in this repository is licensed under the [MIT License](./LICENSE). ## Deploy - Deploy the [Pepesto MCP on Glama](https://glama.ai/mcp/servers/pepesto-solutions/pepesto-mcp).