Czech DIY Retail MCP Server
This server is a read-only MCP server for searching and comparing products, store details, and stock availability across Czech DIY retailers (BAUHAUS, HORNBACH, OBI, Baumax).
Search products across all or selected retailers with optional filters for maximum price and result count.
Get product details by retailer and product ID, including EAN/GTIN, brand, price, category, specifications, images, and availability.
List physical stores for a retailer, with optional filtering by city, postcode, or name.
Check in-store stock for a specific product at a specific store, returning availability status, quantity when exposed, and pickup/reservation flags.
Compare prices across retailers, sorted ascending by price, with per-retailer errors included.
Honor data availability rules: returns
UNKNOWNorNOT_SUPPORTEDrather than inventing stock levels, and never converts missing quantities to zero.
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., "@Czech DIY Retail MCP Server Compare prices for Makita drill across all retailers"
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.
Czech DIY Retail MCP Server (czech-diy-mcp)
Model Context Protocol (MCP) server for Czech DIY retail discovery. The server uses live current retailer pages for BAUHAUS CZ, HORNBACH CZ, OBI CZ and Baumax CZ.
Release status
1.0.0 is the production release. Live product search/detail is implemented for all four retailers; BAUHAUS and OBI expose live store stock, HORNBACH exposes qualitative store offers where present, and Baumax store stock is explicitly NOT_SUPPORTED.
Česká dokumentace
czech-diy-mcp je read-only MCP server pro vyhledávání zboží v českých hobby marketech a stavebninách. Nabízí jednotné rozhraní pro BAUHAUS CZ, HORNBACH CZ, OBI CZ a Baumax CZ.
Server poskytuje:
vyhledávání produktů, cen a kategorií;
detail produktu včetně technických parametrů, EAN/GTIN a obrázků, pokud jsou dostupné;
seznam prodejen;
dostupnost produktu v konkrétní prodejně;
porovnání cen mezi podporovanými prodejci.
Veřejné MCP nástroje jsou search_products, get_product, list_stores, get_stock a compare_price. Primární transport je Streamable HTTP na /mcp; kontrola dostupnosti aplikace je na /healthz.
Rychlé spuštění
uv sync --extra dev
uv run python -m czech_diy_mcp --transport http --port 8000Poté je MCP server dostupný na http://localhost:8000/mcp a health endpoint na http://localhost:8000/healthz.
Docker
docker build -t czech-diy-mcp:1.0.0 .
docker run --rm -p 8000:8000 czech-diy-mcp:1.0.0Důležitá pravidla dostupnosti
Pokud prodejce neposkytne spolehlivý údaj o skladovosti, server vrací UNKNOWN nebo NOT_SUPPORTED. Chybějící množství se nikdy nepřevádí na nulu a server nevymýšlí stav skladu. Skladová data jsou pouze okamžitý údaj a mohou se mezi jednotlivými požadavky změnit.
Server neprovádí objednávky, nepřidává zboží do košíku, nepřihlašuje zákazníky, nezpracovává platby a neřeší CAPTCHA ani jiné interaktivní výzvy.
Bezpečnost provozu
Server nepřijímá libovolné URL a používá pouze pevně definované domény prodejců. Přesto MCP endpoint nevystavujte přímo do veřejného internetu bez TLS, autentizace, rate limitu a firewallu. Podrobnosti jsou v Operations Manual a Security Policy.
Related MCP server: Shoptera Product Intelligence
1. Retailer Support Matrix
Retailer | Priority | Search | Details | Stores | Stock | Quantity |
BAUHAUS CZ | P0 (Primary) | ✅ | ✅ | ✅ | ✅ | Exact numerical stock exposed ( |
HORNBACH CZ | P1 | ✅ live | ✅ live | ✅ live | ✅ live/unknown | JSON-LD stock offers where exposed |
OBI CZ | P2 | ✅ live | ✅ live | ✅ live | ✅ live | quantity/status parsed from the selected store page |
Baumax CZ | P3 | ✅ live | ✅ live | ✅ live |
| retailer exposes no reliable store stock API |
DEK | P4 | 🔮 Future | 🔮 Future | 🔮 Future | 🔮 Future | 🔮 Future |
2. MCP Tools
The server exposes five normalized MCP tools:
search_products(query, retailer="all", max_price=None, max_results=20)Search all live-enabled retailers in production.
get_product(retailer, product_id)Retrieve full product details, GTIN/EAN, specifications, manufacturer info, and retailer-provided in-store positions where available.
list_stores(retailer, query=None)List physical store locations matching an optional query string (city, postcode, name).
get_stock(retailer, product_id, store_id)Query store-specific physical stock availability with maximum 60s cache TTL. When exposed by the retailer, the result also contains
location.row(řada),location.section(sekce), description and source timestamp.
compare_price(query, retailers=None, max_results_per_retailer=10)Compare prices across all four currently enabled retailer adapters; results include per-retailer errors and do not invent unavailable stock.
3. Installation & Local Development
Requirements
Python 3.12+
Setup
uv sync --extra dev4. Operational Commands & Testing
Run Tests with 100% Line & Branch Coverage
uv run pytest -m "not smoke and not container" --cov=czech_diy_mcp --cov-branch --cov-report=term-missing --cov-fail-under=100Run Live Retailer Smoke Suite
pytest -m smokeCode Formatting & Type Checking
uv run ruff check .
uv run ruff format --check .
uv run pyrightMutation testing for critical parsing and comparison logic:
python scripts/run_mutation_audit.py5. Running the MCP Server
Streamable HTTP (Default)
python -m czech_diy_mcp --transport http --port 8000MCP endpoint:
POST /mcpHealth check:
GET /healthz
Stdio Transport
python -m czech_diy_mcp --transport stdio6. Docker Deployment
Build Image
docker build -t czech-diy-mcp .Run Container
docker run -d -p 8000:8000 --name czech-diy-mcp czech-diy-mcpDocker Compose
docker compose up -d7. Configuration
Environment variables (or .env file):
Variable | Default | Description |
|
| Bind host for HTTP server |
|
| Bind port for HTTP server |
|
| MCP endpoint path |
|
| Maximum search results per retailer |
|
| HTTP request timeout in seconds |
|
| Search cache TTL (seconds) |
|
| Product detail cache TTL (seconds) |
|
| Stock lookup cache TTL (seconds) |
|
| Store list cache TTL (seconds) |
|
| Max concurrent requests per retailer |
8. Architecture
MCP Client
│
▼
┌───────────────┐
│ MCP Server │
│ server.py │
└───────┬───────┘
│
▼
┌───────────────┐
│ Service Layer │
│ catalog.py │
└───────┬───────┘
│
┌─────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
BAUHAUS HORNBACH OBI
Adapter Adapter Adapter9. License
10. Documentation
Additional release documentation is maintained in docs/:
Architecture — application boundaries, adapters, data flow and normalized models.
Operations Manual — deployment, health checks, configuration, logs and incident handling.
Development and Testing — local workflow, fixtures, quality gates and live smoke tests.
Release Checklist — reproducible release procedure and acceptance criteria.
11. Data and availability policy
The server is read-only. It never places orders, adds products to baskets, authenticates users, solves challenges or accepts arbitrary URLs.
Retailer data is request-time data and may change between calls. UNKNOWN means that the retailer did not provide a reliable signal; it is never converted to OUT_OF_STOCK, and an absent quantity is never converted to zero. fetched_at is returned with normalized records.
BAUHAUS is the primary production adapter. HORNBACH and OBI provide live catalogue/store integrations; their stock precision depends on the signal exposed by the Czech site. Baumax store stock is intentionally NOT_SUPPORTED where no reliable upstream signal exists.
When BAUHAUS provides shelf placement, get_stock correlates the requested store's live warehouse code with the product detail response and returns the matching position, for example location.row = "174" and location.section = "4". Missing placement data remains null; it is never copied from another store.
12. Release limitations
Retailer pages can rate-limit or challenge automated requests. Such responses are surfaced as structured errors.
Stock is inherently volatile and is cached for at most the configured stock TTL (60 seconds by default).
Exact quantity is returned only when the retailer explicitly exposes it.
The in-memory cache is process-local and is not a shared distributed cache.
DEK is reserved for a future adapter.
Available Tools
5 toolscompare_priceA
Compare product prices across DIY retailers, sorted ascending by price.
Inputs: query (required), retailers, max_results_per_retailer. Returns: Result wrapper for compare_price tool.
get_productB
Get detailed product information by product ID / SKU.
Inputs: retailer (required), product_id (required). Returns: Normalized detailed product model.
get_stockA
Get current product stock level at a specific physical store branch.
Inputs: retailer (required), store_id (required), product_id (required). Returns: Normalized store stock information.
list_storesC
List physical stores for a retailer with optional query filter.
Inputs: retailer (required), query. Returns: Stable structured response wrapper for store discovery.
search_productsC
Search products across Czech DIY retailers (bauhaus, hornbach, obi, baumax, all).
Inputs: query (required), retailer, max_price, max_results. Returns: Result wrapper for search_products tool.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a clearly distinct task: searching, fetching product details, listing stores, checking stock, and comparing prices. There is no meaningful overlap between these operations.
All tool names follow the same snake_case verb_noun pattern, such as search_products, list_stores, and compare_price. The naming is predictable and easy to understand.
Five tools is well-scoped for a retail-focused API covering search, product details, store locations, stock, and price comparison. Each tool serves a clear purpose without unnecessary bloat.
The tool set covers the core read-only workflows for a DIY retail assistant: discover products, inspect details, find stores, check availability, and compare prices. Minor gaps like browsing categories or fetching stock across all stores at once are not critical for the stated domain.
Related MCP Connectors
Search ~8.5M products from 2,500+ Central European e-shops. Semantic, keyword, GTIN lookup.
Search and look up products across thousands of online stores, normalized into one schema.
Search and look up products across thousands of online stores, normalized into one schema.
E-commerce product catalog, pricing, reviews & search API across major retail marketplaces.
1
Related MCP Servers
- AlicenseAqualityCmaintenanceSearch for products available in physical stores near you. Find prices, stock, and store locations for hardware, tools, and construction supplies. Useful when you need something today and can't wait for delivery. 5 tools: search products, search stores, get product details, get store details, list categories. No authentication required. Covers ~2400 products across ~4000 stores in Spain.181Apache 2.0
- AlicenseNot gradedqualityDmaintenanceSearch product catalogs across thousands of Central European e-shops. Semantic search, keyword matching, GTIN/EAN lookup — via REST API or MCP. \~2,500 e-shops | ~8.5M products | 7 countries (CZ, SK, PL, HU, RO, DE, AT)MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to search the toom.de DIY shop, manage a basket per market, check real stock, find markets and articles nearby, compare products, verify whether items fit a car or doorway, and plan pickup routes. It only reads and prepares data — checkout, payment, and article inquiries remain with the user on toom.de.22AGPL 3.0
- AlicenseAqualityBmaintenanceEnables read-only product search, price lookup, and store availability checks across Super zoo storefronts in Slovakia, Czechia, and Poland over stdio or Streamable HTTP.371 npmMIT