kupi-mcp
This server is a read-only MCP tool for working with public Kupi.cz discount offers: searching deals, comparing offers for a product, and optimizing a shopping list across stores.
search_products: search current or date-specific sale products on Kupi.cz with filters for stores, sale-only items, excluded words, membership-only offers, location, sorting (relevance, price, unit price, discount), and a result limit (1–50). Each match includes a confidence score and quality rating.
get_product_offers: fetch and compare all offers for a specific product by slug or HTTPS product URL, sorted by price and unit price, with optional store, location, validity-date, and membership filters.
compare_shopping_list: optimize 1–20 shopping-list items across up to 8 stores, respecting quantities (amount + unit), preferred/required package sizes, allowed/excluded stores, available memberships, and optimization goals (lowest price, fewest stores, balanced). Reports complete/partial coverage, resolved/unresolved items, and package vs. purchase prices.
Location handling: supports preconfigured localities, shows actual location used, warns on mismatch, and never guesses unconfigured locations.
Offer validity checking: filters offers by validity date, never presents future offers as currently valid.
Branch/radius support: can restrict stores to verified branches within a radius, returning branch details and straight-line distance, with clear caveats about assumed applicability.
Package intelligence: parses quantities like "2 kg" or multipacks such as "6 × 0.5 l", computes needed packages, and supports any/preferred/required package-size modes.
Price sanity checks: flags unusually high unit prices relative to comparable candidates (normal/high/extreme) without hard-blocking.
Debug diagnostics: optional structured reason codes, rejected matches/offers, and HTTP request details for transparency.
Safety/limitations awareness: read-only, no login, respects robots.txt, returns structured errors on blocking, and explicitly marks results as approximate rather than confirming stock availability.
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., "@kupi-mcp Porovnej ceny mléka a másla v aktuálních akcích"
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.
kupi-mcp
Neoficiální MCP server nad veřejnými slevovými stránkami Kupi.cz. Pouze čte: vyhledá akční produkty, porovná nabídky jednoho produktu a sestaví z akcí nákupní seznam.
Není spojený s provozovatelem Kupi.cz ani jím schválený.
Nástroje
Nástroj | K čemu je |
| Najde akční produkty. Každý výsledek nese |
| Nabídky jednoho produktu z jeho detailu — víc obchodů než výsledek hledání. |
| Hlavní nástroj: z celého seznamu sestaví proveditelný nákup přes několik obchodů. |
Volitelný parametr radiusKm u prvního a třetího omezí výsledek na řetězce s ověřenou
pobočkou v okolí. Stojí další HTTP požadavky; bez něj server vzdálenost obchodů nezná.
Related MCP server: coffee-price-mcp
Čemu výstup věří a čemu ne
Leták není sklad. Cena z akce neznamená, že produkt na pobočce je.
Vzdálenost je vzdušná čára ze souřadnic pobočky, ne délka jízdy.
Otevírací doba je běžná týdenní; svátky a jednorázová zavření zdroj neuvádí.
Platnost akce na konkrétní pobočce se nedá z veřejných stránek ověřit, proto je označená jako
assumed.Neúplný košík má
totalPrice: null. Cena vyřešené části je vresolvedPrice.Produkt, který dotazu neodpovídá dost jistě, se nepoužije; položka zůstane nevyřešená.
Lokalita
Kupi.cz drží lokalitu v cookies. Endpoint, který překládá název města na interní ID, je
zakázaný v robots.txt, takže se ID nikdy neodhaduje. Buď ho předáte v
KUPI_LOCALITIES, nebo se použije anonymní výchozí lokalita podle IP — a výsledek
vždy uvádí, pro kterou lokalitu data skutečně jsou.
ID si zjistíte ve vlastním prohlížeči z cookies user_locality a user_slocality po
nastavení města na Kupi.cz. Jsou to provozní data; do repozitáře nepatří.
Konfigurace
Proměnná | Výchozí | Význam |
| prázdné |
|
| obecný | User-Agent, kterým se server představuje |
|
| Rozestup mezi požadavky na zdroj |
|
| Souběžné požadavky |
|
| Platnost cache staženého HTML |
|
| Timeout jednoho požadavku |
|
| Opakování po dočasné chybě |
|
| Strop velikosti odpovědi |
Pro HTTP nasazení navíc:
Proměnná | Význam |
| Token, který klient posílá v |
|
|
| Povolené |
| Strop velikosti požadavku (výchozí 1 MiB) |
Bez MCP_HTTP_BEARER_TOKEN a bez výslovného povolení anonymního přístupu endpoint
odpovídá 503. Nezabezpečený server nikdy nevznikne omylem.
Spuštění
npm ci
npm run build
npm startPřes stdio, například v Claude Desktop:
{
"mcpServers": {
"kupi": {
"command": "node",
"args": ["/cesta/ke/kupi-mcp/dist/index.js"],
"env": { "KUPI_LOCALITIES": "Mesto:localityId:sublocalityId" }
}
}
}Nasazení na Vercel
Repozitář je připravený jako drop-in projekt: api/mcp.ts je MCP endpoint,
api/health.ts odpovídá na kořenové cestě. Nastavte MCP_HTTP_BEARER_TOKEN mezi
proměnnými prostředí projektu a nasaďte. npm run package vyrobí ZIP, který se dá na
Vercel přetáhnout beze změn.
Klient se pak připojí na https://vase-nasazeni.vercel.app/api/mcp s hlavičkou
Authorization: Bearer <token>; klienti, které vlastní hlavička Authorization
nepustí, mohou poslat X-Api-Key.
Snapshot poboček
Vyhledávání s radiusKm jinak stahuje stránky poboček za běhu, což je po studeném startu
pomalé. Předgenerovaný snapshot to odstraní:
npm run branches:refresh -- --location Mesto --radius 50Zapíše data/store-branches.json. Opakované běhy pro různá města se slučují. Soubor je
volitelný — bez něj se pobočky dohledávají živě.
Vývoj
npm run typecheck
npm run lint
npm testnpm run privacy:check hlídá, aby se do repozitáře nedostaly e-maily, absolutní cesty
z domovského adresáře ani konkrétní ID lokalit.
Co jsme o zdroji zjistili a proč je kód místy opatrnější, než by se zdálo nutné, je v docs/kupi-facts.md.
Ohleduplnost ke zdroji
Požadavky jsou sériové s rozestupem, odpovědi se cachují a odpovědi 429/403 se
nepřekračují — server se je nesnaží obejít, vrátí strukturovanou chybu. Skupina
User-agent: AI má v robots.txt Kupi.cz úplný zákaz; pro veřejné nebo objemné nasazení
si vyžádejte souhlas provozovatele.
Licence
MIT, viz LICENSE.
Available Tools
3 toolscompare_shopping_listOptimalizovat nákupní seznamARead-onlyIdempotent
Porovná letákové nabídky pro více položek, respektuje obchody, dostupná členství a maximální počet obchodů. Ve výchozím stavu používá jen akce platné dnes. Množství zadávejte přes amount + unit („2 kg“); počet balení se dopočítá podle skutečné velikosti balení (2 kg z balení po 600 g = 4 balení). Produkty s nízkou jistotou shody se nepoužijí a skončí v unresolvedItems. Pokud není pokryt celý košík, je status „partial“ a totalPrice je null — cena vyřešené části je v resolvedPrice. Výsledek je přibližný a neřeší vzdálenost ani sklad.
Inputs: items (required), debug, validOn, location, +6 more. Returns: error, status, stores, success, +17 more
get_product_offersPorovnat nabídky konkrétního produktuARead-onlyIdempotent
Načte veřejný detail /sleva/{slug}, deduplikuje doporučené nabídky a nabídky dle ceny a označí klubové, aplikační a množstevní podmínky.
Inputs: slug, stores, validOn, location, +2 more. Returns: error, success, validOn, location, +8 more
search_productsVyhledat akční produkty na Kupi.czARead-onlyIdempotent
Vyhledá nabídky ve veřejném server-renderovaném HTML Kupi.cz. Ve výchozím stavu vrací jen akce platné dnes; budoucí akce nejsou vydávány za aktuálně platné. Údaje o balení v dotazu („hermelín 100 g“) se automaticky oddělí, aby nekazily hledání. Každý produkt nese match.confidence (0–1) a match.quality (high/medium/low) vyjadřující, jak dobře odpovídá dotazu. Výsledek uvádí skutečnou lokalitu dat; nejde o potvrzení skladové dostupnosti.
Inputs: query (required), debug, limit, sortBy, +6 more. Returns: error, success, validOn, location, +8 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: search products, fetch detailed offers for a specific product, and compare a whole shopping list. There is no meaningful overlap between any pair, and the descriptions emphasize their different inputs and outputs.
All tool names follow a consistent verb_noun pattern in snake_case: search_products, get_product_offers, compare_shopping_list. The verbs clearly indicate the action and the object indicates the resource.
Three tools is a compact but well-scoped set for a narrow domain. Each tool earns its place: search handles discovery, get_product_offers handles per-product detail, and compare_shopping_list handles batch comparison.
The core workflow of searching products, viewing offer details, and comparing a shopping list is covered with no dead ends. Minor gaps exist, such as no explicit store listing or category browsing tool, but these do not undermine the server's stated purpose.
Maintenance
Related MCP Connectors
Danish grocery catalog as MCP tools: live offers across all major chains, stores, EAN lookup, stock.
Live prices, deals & optimal multi-stop shopping routes for German grocery & drug stores.
Read-only shopping decisions, product search, offers, and price history for Greece.
Federated commerce search across independent WooCommerce merchants. Keyless, read-only MCP server.
Related MCP Servers
- FlicenseAqualityBmaintenanceA Model Context Protocol server for real-time Swiss grocery shopping that searches and compares products across 8 major Swiss retailers (Migros, Coop, Aldi, Denner, Lidl, Farmy, Volgshop, Otto’s), normalizes per-unit prices, surfaces promotions, computes optimal multi-store shopping plans, and works with any MCP-compatible client without API keys or accounts.7215 npm46-
- AlicenseAqualityDmaintenanceA read-only MCP server that wraps the coffee.pryzm.gg public API to calculate effective prices of coffee drinks after discounts, enabling users to find the cheapest coffee deals, search for discounts, and verify receipt prices.32MIT
- AlicenseAqualityFmaintenanceRead-only MCP server for Greek supermarket product and price data from PosoKanei. Enables product search, barcode lookup, price comparison across retailers, and basket evaluation.1053 npm5MIT
- AlicenseAqualityAmaintenanceMCP server for Danish grocery stores with home delivery: nemlig.com, BilkaToGo and REMA 1000. It searches offers, compares a whole basket across stores and fills the cheapest cart, but never orders or pays.142,257 PyPI156MIT