MercadonaMCP
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., "@MercadonaMCP Search for 'leche' in postal code 28001 and show me the top 5 products."
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.
MercadonaMCP
Status: v0.1.1 personal macOS MVP. Unofficial, pre-release software.
MercadonaMCP is a local Model Context Protocol companion for searching Mercadona Online products and reading or carefully updating a user's cart from the command line or ChatGPT Web.
It is not affiliated with, endorsed by, or supported by Mercadona or OpenAI. It never checks out, places an order, accesses payment data, or reserves a delivery slot.
What it does
Opens a dedicated, visible Chrome session for the user to log into Mercadona; the project does not receive or store the password.
Keeps minimized Mercadona session material in macOS Keychain.
Searches up to ten concise Spanish product phrases per request and returns bounded, normalized candidates.
Reads the authenticated cart.
Sets exact final cart quantities with version checks, idempotent operation IDs, and post-write verification.
Exposes those capabilities to ChatGPT through a private OpenAI Secure MCP Tunnel during development.
Related MCP server: Kroger MCP Server
Architecture
ChatGPT Web -- OpenAI Secure MCP Tunnel -- tunnel-client -- STDIO -- MercadonaMCP
|
macOS Keychain
|
Mercadona HTTPS APIsThe Mercadona token remains on the Mac. Product and cart data requested in a ChatGPT conversation necessarily travel through ChatGPT to answer that request. Read the detailed architecture, data flow, and network boundary before connecting an account.
Requirements
macOS with an unlocked login Keychain session.
Python 3.12+ and uv.
Google Chrome.
A Mercadona Online account in a supported delivery area, for authenticated cart use.
ChatGPT Developer Mode and OpenAI's
tunnel-client, only for ChatGPT Web integration.
Install
From a checkout of this repository:
uv sync --locked
uv run playwright install chrome
uv run ruff check .
uv run mypy src tests
uv run pytestThe default test suite is offline. It does not need Chrome, a Keychain secret, a Mercadona account, or network access.
First local use
Check the starting state, then authenticate in the Chrome window that opens:
uv run mercadona auth status
uv run mercadona login
uv run mercadona auth statusSearch products using either a five-digit delivery-area postal code or a known Mercadona warehouse code:
uv run mercadona search "leche" --postal-code 28001 --limit 5
uv run mercadona product PRODUCT_ID --postal-code 28001
uv run mercadona cart showPRODUCT_ID and postal code must be appropriate for the user's own delivery
area. Catalog reads do not alter the cart.
Cart updates
Cart updates are deliberately explicit. The CLI requires a live-write opt-in, a fresh cart version, a caller-provided operation ID, and an interactive confirmation after showing a preview:
uv run mercadona cart set PRODUCT_ID FINAL_QUANTITY \
--expected-version CURRENT_CART_VERSION \
--operation-id unique-operation-id \
--allow-live-writeFINAL_QUANTITY is absolute: 0 removes the product, while 2 means the
cart should contain exactly two. After the write, MercadonaMCP re-reads the
cart and verifies the requested result. Reusing the same operation ID with the
same request returns the prior result instead of making another write.
For a safe manual procedure—including restoring the original quantity—follow the manual testing runbook. Never use this project for checkout, payment, delivery-slot, or order-placement workflows.
ChatGPT Web (private development integration)
The Web integration uses OpenAI's official tunnel-client; it is not a public
deployment. Configure a tunnel profile and store its distinct runtime API key
in macOS Keychain as described in ChatGPT Web setup.
Normal use is:
./scripts/mercadona-tunnel doctor --explain
./scripts/mercadona-tunnel runKeep the tunnel process running while creating or using the ChatGPT plugin. The
profile launches uv run mercadona-mcp itself, so do not start a second STDIO
server manually.
MCP tool reference
Tool | Effect |
| Reports whether a usable local Mercadona session exists. |
| Searches one concise product phrase; defaults to five candidates (max 10). |
| Searches up to ten independently labelled product phrases; partial failures stay scoped to their query. |
| Returns normalized details for one product. |
| Reads the current authenticated cart. |
| Destructive: sets absolute quantities after the host obtains confirmation. |
update_cart requires items, expected_cart_version, and operation_id.
It is marked destructive in MCP metadata. ChatGPT must display the proposed
change and obtain confirmation before calling it. The server cannot itself
prove that a host rendered a human-confirmation UI; do not enable cart updates
on a host where that assurance is unreliable.
Security and privacy
Passwords are entered only on the user-visible Mercadona or Google pages.
Session material is stored through macOS Keychain; no plaintext session file is created by the project.
The authenticated client only permits HTTPS requests to
tienda.mercadona.es.Tool results use normalized models and do not contain tokens, cookies, authorization headers, browser state, or raw upstream responses.
Product names and descriptions are untrusted data, not instructions.
These are implementation boundaries, not a claim that the system is risk-free. For details, tradeoffs, and reporting guidance, read SECURITY.md and THREAT_MODEL.md.
Limitations
macOS and Google Chrome are the only supported login environment.
Product search opens a short-lived, isolated visible Chrome window. The provider currently rejects the equivalent direct HTTP request, so this behavior can need maintenance if the website changes.
Mercadona endpoints are observed web behavior, not a documented partner API; they can change or stop working.
Availability and prices depend on delivery area and can change.
The tunnel is intended for personal/private development. It is not a public hosted MCP endpoint or a Plugin Directory submission path.
The idempotency replay cache is in memory for ten minutes; restarting the MCP server clears it.
A compromised Mac, browser, Mercadona account, ChatGPT account, or external service can exceed the protections of this local project.
Troubleshooting
Symptom | What to do |
| Run |
Chrome cannot launch | Confirm Chrome is installed at the standard macOS location and run |
Cart version conflict | Read the cart again and retry with its current version; do not overwrite it blindly. |
Cart-write result is ambiguous | Read the cart and compare requested final quantities before trying another operation ID. |
ChatGPT cannot reach tools | Keep |
Tunnel missing from ChatGPT | Associate the tunnel with the target ChatGPT workspace and confirm Tunnels Read + Use; see ChatGPT Web setup. |
Development and documentation
License
Release notes
See CHANGELOG.md, known limitations, and the personal-MVP release checklist.
Available Tools
6 toolsauth_statusA
Return whether a usable local Mercadona session is available.
Inputs: no named parameters. Returns: object
get_cartA
Read the current authenticated Mercadona cart without changing it.
Inputs: no named parameters. Returns: object
get_productB
Get normalized details for one product in an opaque warehouse code.
Inputs: warehouse (required), product_id (required). Returns: object
search_productsA
Search one concise Spanish product phrase; never send a full instruction.
Use product nouns and important constraints, for example helado chocolate
or pepino holandés. For several products use search_products_batch.
For conceptual requests, try a few plausible Spanish phrases. This tool never
traverses the complete catalogue as a fallback.
Inputs: query (required), warehouse (required), limit. Returns: result
search_products_batchA
Search several concise Spanish product phrases concurrently and independently.
Use one query per requested product or product family. Preserve each caller key, inspect candidates before selecting a product ID, and do not submit a whole shopping instruction as one query. A failure for one query is returned in that query's result without discarding successful candidates.
Inputs: queries (required), warehouse (required). Returns: object
update_cartADestructive
Set exact final quantities after the host obtains explicit user confirmation.
Inputs: items (required), operation_id (required), expected_cart_version (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools map to distinct actions: auth, search, product detail, and cart read/write. The only potential confusion is search_products versus search_products_batch, but their single-query versus batched-concurrency scope is clearly described.
Tool names mostly follow a clear verb_noun pattern: search_products, get_product, get_cart, update_cart. auth_status is the only deviation and would fit better as get_auth_status.
Six tools is a well-scoped size for a Mercadona shopping assistant. Each tool serves a practical purpose with no obvious redundancy.
The tool surface covers the core workflow: session status, product discovery via search, product details, and reading/updating the cart. No obvious missing operation prevents normal use.
Maintenance
Related MCP Connectors
Hosted MCP for e-commerce: live product catalog, stock, and pricing for AI agents.
Idealista MCP server for ChatGPT, Claude and any AI agent: list my listings, update listing, renew listing and reply to lead in your own Idealista account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Idealista yourself; Cotlet does not store your password and you need no Idealista API key. About the official Idealista API: Idealista has no public API for your own listings or contacts (checked 11 Oct 2026). Its Search API is read-only and given only after an application, and its official Claude and ChatGPT app only searches public listings, with no login. Setup and FAQ: https://cotlet.dev/integrations/idealista-api-mcp-server
AnyList MCP server for ChatGPT, Claude and any AI agent: list shopping lists, add list item, cross off item, read recipe, create recipe, add recipe to meal plan and add meal plan ingredients to list in your own AnyList account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to AnyList yourself; Cotlet does not store your password and you need no AnyList API key. About the official AnyList API: AnyList has no public API, developer docs or official MCP server (checked 25 Oct 2026). The official connections are voice entry with Siri and Amazon Alexa, and an iCalendar link that shows your meal plan in a calendar app. Setup and FAQ: https://cotlet.dev/integrations/anylist-api-mcp-server
Product search for AI agents: Amazon + Shopify, cart-to-checkout buy path. Pay-per-call, no API key.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with the Rami Levy Online Grocery Store API, allowing users to perform product searches, add or remove items from their cart, and prepare for checkout, all while integrating with MCP-enabled LLMs.11MIT
- AlicenseNot gradedqualityDmaintenanceAllows Large Language Models to interact with Kroger's grocery services, enabling product search, store lookup, and cart management through the Model Context Protocol.3MIT
- 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
- AlicenseNot gradedqualityDmaintenanceEnables personalized Mercadona grocery orders via natural language, with Nutri-Score prioritization and supervised cart execution (no payment). Supports user intake, product search, and integration with external menu systems.1MIT