Skip to main content
Glama

alza-mcp-community

Let your AI agent shop on Alza.cz — Central Europe's largest e-commerce store.

Unofficial, community-built project. Not made, endorsed or supported by Alza.cz a.s.

npm version CI License: MIT TypeScript Playwright MCP

alza-mcp-community is an unofficial Model Context Protocol server that gives Claude (or any MCP-aware agent) an interface to Alza through browser-based catalog scraping and reverse-engineered mobile/web APIs: search products, pull full detail, read reviews, use anonymous/account data, manage a cart, select delivery/AlzaBox pickup, preview checkout, and submit an order only with an explicit one-time confirmation token.

Ask: "Find me the best pro-grade wheel cleaner under 600 Kč and tell me where I can pick it up in Prague." The agent calls search_products → get_product → find_pickup_points and gives you a real answer with real prices and a real address.

IMPORTANT

This project isunofficial — not affiliated with, endorsed by, or sponsored by Alza.cz a.s. It's a community wrapper for personal/research use. Read the disclaimer before deploying or sharing widely.


Quick install

NOTE

Renamed from alza-mcp. At Alza's request, the project is now alza-mcp-community, so it's clear it isn't an official Alza product. If you installed the old package, replace alza-mcp with alza-mcp-community in your MCP config. Your saved login in ~/.alza-mcp/ keeps working.

One-click install

Install in Cursor Install in VS Code

Both buttons install the same thing as the manual config below: npx -y alza-mcp-community, no environment variables, no secrets. With npx/npm, install runs a postinstall step that downloads Playwright's headless Chromium (~92 MB) and sets up the optional curl_cffi venv, so the first install takes a while and later starts take a few seconds. The .mcpb bundle and --ignore-scripts installs skip postinstall: Chromium is then downloaded on the first browser-backed call (~30 s) and the venv is not created (see Install paths). For Claude Desktop, download the one-click alza-mcp-community-<version>.mcpb bundle from the latest release and open it, or use the JSON config below.

Claude Code

claude mcp add alza --scope user -- npx -y alza-mcp-community

That's it. Restart Claude Code, type /mcp to confirm, and start asking. The install downloads Playwright's headless Chromium browser (~92 MB) via postinstall; if that was skipped, the first browser-backed call downloads it (~30 s).

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "alza": {
      "command": "npx",
      "args": ["-y", "alza-mcp-community"]
    }
  }
}

Restart the app. Same install-time download.

Cursor / Continue / any MCP client

Same shape — command: "npx", args: ["-y", "alza-mcp-community"]. Stdio transport, standard MCP everywhere.


Related MCP server: Instacart MCP Server

What you can ask

A real session captured during testing:

You: Find me the best pro-grade wheel cleaner on Alza, around 500 Kč. I want a detailer-tier brand.

Claude: (calls search_products "čistič disků kol" sort=rating, then get_product on the top picks)

Top three from the live catalog:

#

Product

Brand

Volume

Price

★

1

Sonax Xtreme Full Effect

Sonax 🇩🇪

750 ml

559 Kč

4.8

2

Kenotek Wheel Cleaner Ultra

Kenotek 🇧🇪

1 L

455 Kč

4.8

3

Auto Finesse Reactive 1L

Auto Finesse 🇬🇧

1 L

599 Kč

4.4

Pick: Sonax Xtreme Full Effect 750 ml — the de-facto detailer recommendation. It's iron-fallout reactive (turns purple on contact with brake-dust particles so you can watch it work), Sonax is a German workshop standard, and it's in stock.

That's the agent calling four MCP tools across two parallel searches and synthesizing real Alza data. No hallucinated SKUs.


What it does

With 63 domain tools (66 including list_toolsets, set_toolset and report_issue), listing every tool on every tools/list call would front-load an agent's context with dozens of tools it may never touch in a given conversation. So they're grouped into toolsets, and only two are enabled by default, exposing 15 domain tools plus the two toolset controls and report_issue:

Toolset

Enabled by default?

Covers

catalog

✅

Search, product detail, side-by-side comparison, reviews, categories, pickup-point lookup

auth

✅

OAuth handshake, account status, the mutation-token issuer

basket_and_checkout

—

Cart, delivery/pickup selection, checkout, order placement & cancellation

account_management

—

Profile, contacts, addresses, registration, credential/identity changes

orders_and_payments

—

Order history, payment methods, after-order payments, claims, documents

reviews_and_subscriptions

—

Reviews, complaints, AlzaSubscription, attachments, EAN lookup

watchdogs

—

Alza's native price-drop / back-in-stock watchdog (list, set, delete)

chat

—

Alza's in-app chatbot

pc_builder

—

Compatibility-checked PC parts lists: pc_build_check, pc_build_suggest

advanced_raw

—

mobile_read, the untyped escape hatch

Call list_toolsets to see every group and set_toolset({id, enabled: true}) to turn one on before using its tools — e.g. enable basket_and_checkout before adding something to a cart. This is standard MCP progressive disclosure (RegisteredTool.enable()/.disable(), which fires the normal tools/list_changed notification) — no functionality is removed, it's just not all visible at once.

Reporting problems. report_issue is always available, whichever toolsets are on. When a tool fails unexpectedly, returns clearly wrong data, or breaks because Alza changed something, the server instructions and the error message itself point the agent to it. It returns a redacted draft (with version, Node, platform, storefront, transport and this session's recent tool errors), a gh issue list command to check for duplicates, a ready-to-run gh issue create --repo lukabudik/alza-mcp-community … command, and a prefilled new-issue link for agents without a shell. The server files nothing itself: the agent shows the draft to you and files it from your GitHub account only if you agree. Credentials (including cookies and API keys), e-mails, phone numbers, UUIDs, URL query values, account ids and home-directory paths are redacted automatically, and recent errors keep only route and status. Invalid arguments and unknown products don't trigger the hint.

Catalog tools:

Tool

Purpose

search_products

Keyword search, price/stock/screen-size filters, and bounded client-side sorting (price filters and sorts apply to the top ~72 ranked candidates, pageSize is the real cards-per-page, hasMore/nextPage page on; an inverted price range or a blank query is rejected); brand/attribute filters use category pages and ignore query

get_product

Full detail for one product — price, availability, brand, image, URL

compare_products

2–6 products side by side — one aligned table of price, availability, rating and every spec row; optional summarize: true verdict via MCP sampling when the client supports it

get_product_reviews

Aggregate rating + review count + individual reviews (author, date, rating, body, pros/cons) via the reviews API, newest first; the list may be longer than the aggregate count (it appears to include other storefronts' reviews)

recommend_alternatives

Cheaper / better-rated / same-brand alternatives to a product (Alza's own alternatives list, same-category search fallback)

find_pickup_points

Nearest AlzaBox lockers and AlzaShop showrooms by 5-digit postal code, merged by distance, with opening hours, no cart needed. The postal code is geocoded with the public OpenStreetMap Nominatim service (nominatim.openstreetmap.org), so the normalised code and country are sent to that third party (not to Alza); results are cached for a week. It can't tell whether a specific product fits an AlzaBox; use delivery_options for that

list_category_filters

Category brands (brands[].valueId) and attribute facets with live ids/counts — use producer_ids or filters with category_id ({param_id, value_id} for checkbox facets, {param_id, min?, max?} for slider ranges such as screen size or refresh rate); unsupported URL filters return an error (checkbox values work only where Alza publishes a landing page for the value — HDMI does, monitor panel type and resolution do not)

get_deals

Discounted products on alza.cz and alza.sk: the price you can pay now (priceNow, including promo-code prices such as Alza dni "Kúpiť s kódom ALZADNI15" with promoCode/promoPercent), list and older crossed-out prices, badge (SUPER CENA, ZĽAVNENÉ -N %, CENOVÁ BOMBA, NOVINKA), savings, monthly instalment, AlzaPlus+ member/non-member prices, and a discount % computed from the observed prices. A priceCheck flags cards where the code price is not list × (1 − percent). Scans a category_id or any listing url on the storefront (e.g. /monitory-23-a-24/alza-dni/18848792-e39.htm), following page links until no new products appear (max 5 pages), or popular categories when omitted. If Cloudflare challenges the headless browser, set ALZA_CDP_URL to use your own Chrome

list_categories

Top-level categories, or real subcategories when parent_id is supplied — feed the returned ids into search_products

autocomplete

Search-box suggestions over plain HTTP (no page render): phrases, categories, brands and products with ids/codes — refine a messy Czech query before search_products

product_by_ean

Looks up catalog products by barcode/EAN (the app's camera barcode-scan API, AT3; read-only, no account required; enable reviews_and_subscriptions)

PC builder tools (enable pc_builder):

Tool

Purpose

pc_build_check

Checks a parts list (Alza codes). Checks socket, RAM generation/slots, PSU wattage + headroom, GPU length and cooler height/radiator vs case, form factors, and display output. Returns prices, total, stock, and one verdict per rule with the spec values used

pc_build_suggest

Proposes a compatible build within a CZK budget from Alza's real component categories (gaming / workstation / office, pinned fixed_parts, bounded detail fetches)

Account and checkout tools:

Tool

Purpose

auth_start

Creates a mobile-API OAuth PKCE authorization URL

auth_exchange

Exchanges the returned authorization code for mobile-API tokens

auth_discovery

Reads live OIDC metadata from identity.alza.cz

mobile_read

Reads fixed APK-confirmed catalog, navigation, account, order-history, list, branch, alternative-product, basket, cost-estimate, web after-payment-dialog, web zip-code (WCF GetZipCodes twin), and chatbot-navigation capabilities

prepare_mutation

Creates a one-time token for a fixed, source-confirmed mutation without sending a request; the token is bound to the action and the exact call arguments (payload) and expires after 5 minutes

mutate_list

Executes a validated APK-confirmed low-risk mutation (lists, coupons, basket, country/ISIC, gift, watchdog, feedback, discussion) with that token

account_status

Checks whether a mobile API access token is loaded

cart

Reads the current cart and total

add_to_cart

Adds a product by Alza code

delivery_options

Reads delivery + AlzaBox/pickup options from the APK getDeliveryPaymentGroups endpoint

select_pickup_point

Despite the name, returns the delivery → payment associations from getDeliveryAssociations (which payments fit a delivery, and the delivery fee under each). It does not pick a pickup point: re-tested on an authenticated cart on 2026-10-06. To choose an AlzaBox, use web_pickup_places → web_place_order with parcel_shop_id.

checkout_preview

Previews checkout and returns a one-time confirmation token

cancel_order

Cancels an order part using its cancel form, a reason, and a one-time prepare_mutation token

place_order

Runs the mobile API order sequence only when supplied the preview token and required API payloads

web_pickup_places

Reads the live web pickup family (AlzaBox/branches/24-7 availability, place list, place detail) for web-checkout delivery selection (read-only)

web_add_to_cart

Adds a product to the live web HATEOAS basket (basket/v1/items, visitor-keyed) and returns the extracted basket id

web_cart

Reads the live web checkout cart state + item list for a basket id from web_add_to_cart (read-only)

chat_navigation

Reads the live chatbot HATEOAS navigation (chatbotapi.alza.cz, server-provided chat actions; read-only)

chat_send

Opens/continues a chatbot session with page context (session-scoped, visitor-keyed; returns {configuration, showChat})

User-management, payments, orders, and post-purchase tools:

Tool

Purpose

profile

Reads the authenticated profile + address book (APK getUserData)

contacts

Reads the account contact list

register

Registers a new Alza account (credential-bearing, one-time token)

address_upsert

Creates/edits a delivery address through the server-provided address form

address_delete

Deletes a delivery address via its per-address action

address_search

Zip/city search via the verified getZipCodes lookup, or a profile addressSearchAction if one is supplied (read-only)

payment_methods

Lists payment methods from the APK delivery-payment-group endpoint

after_order_payments

Lists after-order payment options for an order part

pay_after_order

Executes an after-order payment (APK AfterOrderRequestBody, one-time token)

web_place_order

Places an order through the live-verified legacy web WCF pipeline (SaveOrder2→3, 113-gate retry, CheckOrder4, SendOrder4; one-time token) — the working submission path while mobile sendOrder3 500s

web_pay_after_order

Executes a web after-order payment through the live-verified WCF CreateAfterPayment (one-time token)

order

Reads a user order by numeric user_id + order_id (+ optional part detail, milestones, invoice refs)

review_submit

Submits a product review through the server-provided review form

complaint_claims

Lists active or archived warranty claims by user_id (K1; read-only)

subscription_overview

Reads the account's subscription section (the navigation's userSubscription link) by user_id (S1; response shape not yet live-verified)

subscription_activate

Activates AlzaSubscription (one-time token)

subscription_update_installment

Changes the installment plan (one-time token)

upload_attachment

Uploads image attachments via the multipart server-provided action (one-time token)

order_search

Searches the account's orders by term (OR6; read-only)

order_archive

Reads the account's archived orders (OR7; read-only; the "Skrýt zrušené" include/hide-cancelled toggle)

order_document

Downloads an order invoice/document from its server-provided href (OR10; origin-validated to the Alza host family; the body is returned in structuredContent only)

gdpr_info

Reads the GDPR section + export dialog (A17; read-only — where the data export will be sent)

claim_detail

Reads one warranty claim's detail from its detailAction link (K2; read-only; pinned to the warranty-claims routes)

change_password

Changes the account password (A14; one-time token; logs the user out of every device)

two_factor_set

Enables/disables SMS two-factor (A15; one-time token)

phone_change

Changes the contact phone number (A16; one-time token)

email_change

Changes the contact email (A16 sibling; one-time token)

delete_account

Deletes the account (A18; one-time token; irreversible — disposable accounts only)

watchdog_list

Lists the account's Alza watchdogs: price-drop and back-in-stock alerts (B9a; read-only; no email in the output)

watchdog_set

Sets a watchdog on a product (max_price and/or track_stock). Alza emails the account when the condition is met (B9; one-time token)

watchdog_delete

Deletes a watchdog by watchdog_id or commodity_id (B9b; one-time token)

High-impact mutations require one-time confirmation tokens (checkout_preview for mobile place_order, prepare_mutation for the other guarded mutations); the full route inventory, exposure decisions, and verification labels live in docs/mobile-endpoint-coverage.md.

OAuth sign-in happens outside the MCP; auth_exchange exchanges the returned code and the server holds access/refresh tokens in memory or loads them from the configured token file. An access token that is expired (or within 60 s of its JWT exp) is refreshed before the next account call, and parallel calls share one refresh. account_status reports expiresAt/expired. When the tokens were loaded from the token file, refreshed tokens are written back to it (atomically, mode 0600), so a restart does not begin with a stale token; tokens from an in-process auth_exchange stay in memory.

"Při přihlášení došlo k chybě." after signing in? The sign-in usually worked. Alza redirects to alza://identity?code=…&state=…, which a desktop browser can't open, so the page stalls and a 40-second timer in Alza's login page shows that message. Before signing in, open DevTools and turn on Network → Preserve log. After you sign in, copy the alza://identity?code=… URL from the redirect's Location header, or from the Console error about failing to launch alza://. Pass the whole URL to auth_exchange as code. The code expires quickly, so exchange it right away. Registration and credential-change tools do accept passwords or verification codes as arguments, guarded by one-time confirmation tokens. Account/cart/order tools issue API requests and can fall back to browser-backed requests when challenged; they do not automate checkout forms.

Checkout paths: web_place_order submits the cart populated by add_to_cart, after delivery_options and any cart-scoped web_pickup_places lookup. The web_add_to_cart → web_cart HATEOAS basket is separate. The mobile place_order route was blocked by server-side HTTP 500 in the recorded live tests; the legacy WCF path was live-verified. See known limitations for dated evidence.

Mobile API environment variables:

Env var

Purpose

ALZA_API_BASE_URL

Mobile API base URL, default https://www.alza.cz

ALZA_VISITOR_ID

Optional anonymous visitor UUID; otherwise generated per process

ALZA_OAUTH_CLIENT_ID

OAuth client id used by auth_start, auth_exchange and token refresh, default alza_Android. Change it only together with ALZA_OAUTH_CLIENT_SECRET

ALZA_OAUTH_REDIRECT_URI

OAuth redirect URI, default alza://identity

ALZA_COUNTRY / ALZA_CULTURE

countryCode / culture sent on the OAuth authorize URL, default: the ALZA_BASE_URL storefront's (CZ / cs-CZ for alza.cz, SK / sk-SK for alza.sk)

ALZA_OAUTH_AUTHORITY

OAuth authority, default https://identity.alza.cz

ALZA_OAUTH_CLIENT_SECRET

The alza_Android OAuth client is confidential — token requests need its APK-embedded secret (default: the source-verified value; set "" to omit it for public clients). Used by auth_exchange and token refresh

ALZA_CLIENT_SECRET

Same secret for the PKCE exchange scripts (scripts/e2e-order-payment.browser.mjs exchange, scripts/alza-auth-exchange.mjs)

ALZA_TOKEN_FILE

JSON token store written by scripts/alza-auth-login* / scripts/alza_auth_login.py (default ~/.alza-mcp/tokens.json; set none to disable auto-load). The server rewrites it (atomic, 0600) after refreshing tokens it loaded from it; with none it is neither read nor written

Plus:

  • 📦 Resource — alza://product/{code} lets agents read a product as a URI.

  • 💬 Prompt — /find-product is a guided shopping helper.

  • 🌍 Multi-locale — catalog locale configuration supports alza.cz, .sk, .hu, .at, .de, .co.uk via ALZA_BASE_URL. The API calls (autocomplete, individual reviews, alternatives, navigation, chatbot, account reads) send that storefront's country and Accept-Language; webapi.alza.cz and chatbotapi.alza.cz serve every storefront and pick it from country (live-verified for alza.sk 2026-10-12). Account/checkout verification is for CZ only, and the account writes (2FA, phone, email, account deletion, watchdogs, basket unlock) keep sending country=CZ.


Configuration

All optional — alza-mcp-community works out of the box.

Env var

Default

Purpose

ALZA_BASE_URL

https://www.alza.cz

Switch locale: https://www.alza.cz, .sk, .hu, .at, .de, .co.uk

ALZA_CDP_URL

unset

Connect to your already-running Chrome via CDP instead of launching a managed Chromium. Pages open in a fresh browser context, so your Chrome's Alza cookies are not used (see Your own prices for that); set ALZA_MCP_SKIP_INSTALL=1 separately to skip the installation-time download. Launch Chrome with --remote-debugging-port=9222 and set ALZA_CDP_URL=http://localhost:9222.

ALZA_WEB_SESSION_FILE

~/.alza-mcp/web-session.json

Signed-in web session written by --login and used by the catalog tools when the file exists. Set none to ignore it. See Your own prices.

ALZA_TOOLSETS

unset

Toolsets to enable at startup in addition to the default catalog + auth, comma-separated (basket_and_checkout,orders_and_payments) or all. For MCP clients that do not reload the tool list after set_toolset (they ignore notifications/tools/list_changed), so the basket, order and account tools are visible from the first tools/list. Ids: see list_toolsets; an unknown id stops the server at startup.

ALZA_TOOLS_ALLOW

unset

Tool names this deployment exposes, comma-separated (search_products,get_product,cart). Every other tool — list_toolsets, set_toolset and report_issue included — is removed, so no call can bring it back; the allowed tools are enabled from the start. For handing the server to an agent you do not fully trust (e.g. a remote connector). An unknown name stops the server at startup.

ALZA_MUTATION_ACTIONS_ALLOW

unset

prepare_mutation actions that may be issued a confirmation token, comma-separated (coupon_add,watchdog_set). Every guarded write needs that token, so other actions cannot run; the action enums of prepare_mutation and mutate_list shrink to the list. An unknown action stops the server at startup.

ALZA_PERSIST_SIGNIN

unset

1: a sign-in completed in this process (auth_start → auth_exchange) is written to ALZA_TOKEN_FILE and refreshed there, so it survives a restart. By default an in-process sign-in stays in memory and never overwrites the store, since it may be another account. For a long-lived deployment whose operator signs in through the running server instead of scripts/alza-auth-login.mjs.

ALZA_HEADLESS

true

Set false to show the browser used for scraping and API fallback; OAuth/MFA/payment interactions remain user-controlled

ALZA_IDLE_TTL_MS

180000

Close the headless Chromium after this many ms with no tool calls. Lower it on memory-constrained machines; raise it (or disable by setting absurdly high) if you make many calls in quick succession and don't want the relaunch latency.

ALZA_PROXY_URL

unset

Route Alza traffic through an HTTP(S) or SOCKS5 proxy (http://user:pass@host:port, socks5://host:port), for example a residential proxy when this machine's IP gets Cloudflare challenges (datacenter and CI IPs do). Used by the managed Chromium and the curl_cffi sidecar. While it is set, the account stack never falls back to an un-proxied plain fetch (only to the managed browser), and with the sidecar disabled (ALZA_CF_TRANSPORT=0) OAuth, AppAction and document requests are refused instead of sent directly, so a proxy failure is reported instead of bypassed. An invalid value stops the server at startup with a one-line error. Not proxied: ALZA_CDP_URL browsers and multipart uploads (upload_attachment), which the sidecar cannot carry.

ALZA_DEBUG

false

Verbose stderr logging (equivalent to ALZA_LOG_LEVEL=debug)

ALZA_LOG_LEVEL

info

Minimum stderr log level: debug, info, warn or error

ALZA_CF_TRANSPORT

enabled

Set 0 to disable the Chrome-fingerprint curl_cffi sidecar (the account stack then uses plain fetch and the browser)

ALZA_CF_PYTHON

auto

Python interpreter that has curl_cffi. Default search order: this variable, .venv-cf in the package (bin/python, or Scripts\python.exe on Windows), then python3 (python/py on Windows)

Your own prices (signed-in catalog)

By default the catalog tools browse alza.cz anonymously and return public prices. If your Alza account gets different prices (a company price list, for example), sign in once:

npx -y alza-mcp-community --login

This opens your installed Chrome (or Edge) on the storefront. Sign in there yourself, then press Enter in the terminal or close the window. The cookies are saved to ALZA_WEB_SESSION_FILE (~/.alza-mcp/web-session.json, mode 0600), and from the next browser start every catalog page loads signed in, so search_products, get_product, compare_products, get_deals and pc_build_* return the prices Alza shows your account. recommend_alternatives signs in for the source product, but its candidate list comes from the mobile API and keeps public prices. The password never passes through the server.

It is opt-in: nothing changes until you run --login. To go back to public prices, delete the file or set ALZA_WEB_SESSION_FILE=none. Cookies Alza refreshes while the server runs are written back when the browser closes, unless a newer --login replaced the file meanwhile. When the sign-in expires, Alza serves the pages signed out; the server notices (Alza's page data reports logged_out), logs a warning, and adds a note to every price result telling the agent the prices are public and that you should run --login again. This session is separate from the mobile-API OAuth login (auth_start → auth_exchange, ALZA_TOKEN_FILE), which the account, cart and order tools use. Over HTTP it is not loaded unless you set ALZA_HTTP_ALLOW_WEB_SESSION=1.

Install paths and the curl_cffi venv

The Chrome-fingerprint sidecar needs a Python venv with curl_cffi (pinned to >=0.16,<0.17, the tested range). What each install path does:

Install path

Chromium headless-shell

curl_cffi venv

npx -y alza-mcp-community / npm i alza-mcp-community (Linux, macOS, WSL, MSYS bash)

downloaded by postinstall

created by postinstall if bash and python3 (with venv) exist; a failed attempt removes the partial venv

ALZA_MCP_SKIP_INSTALL=1 or PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1

skipped (downloaded at runtime when needed)

still created

ALZA_MCP_SKIP_VENV=1

downloaded

skipped

--ignore-scripts, or the .mcpb bundle

downloaded at runtime when needed

not created. For --ignore-scripts run npx -y alza-mcp-community --setup-cf (cross-platform, no bash) or bash scripts/ensure-cf-venv.sh in the package directory; for the .mcpb bundle run --setup-cf once and point ALZA_CF_PYTHON at any interpreter that has curl_cffi

This repository's own checkout (npm ci)

skipped

skipped; run npm run setup:cf and npx playwright install chromium --only-shell yourself

Without the venv the server still works: the account stack falls back to plain fetch and the browser, which Cloudflare challenges more often. Windows: the interpreter lookup also tries .venv-cf\Scripts\python.exe, python and py, and the bash script does not run on plain Windows. Use npx -y alza-mcp-community --setup-cf instead: it is implemented in Node, finds py -3/python/python3, runs python -m venv .venv-cf in the package directory, installs curl_cffi>=0.16,<0.17, verifies the import, prints success or failure and exits 0/1. It is idempotent, removes a venv it half-built if pip fails, explains the Windows 260-character path limit when a failure happens in a long install path (enable LongPathsEnabled or install in a shorter folder), honours ALZA_MCP_SKIP_VENV=1, and is never run automatically (the server never installs packages at runtime; when the sidecar is unavailable it only logs a one-line hint to run it). The venv is created inside the package copy that runs the command (for npx, its cache directory, which is replaced when a new version is fetched or the npm cache is cleared; re-run --setup-cf then), so the .mcpb bundle, which has its own directory, does not pick it up: after running it, set ALZA_CF_PYTHON to the interpreter it prints (or to any interpreter that has curl_cffi) in the bundle's environment. The Windows path (Scripts\python.exe, py -3) is unit-tested with mocked processes only and is unresolved on a real Windows machine (not tested live).


Running over HTTP (Streamable HTTP)

stdio is the default and what the install snippets above use. To serve the same server over MCP Streamable HTTP instead, for example for a client that only takes a URL:

npx -y alza-mcp-community --http --port 3000          # or: ALZA_TRANSPORT=http ALZA_HTTP_PORT=3000 npx -y alza-mcp-community
# → MCP endpoint http://127.0.0.1:3000/mcp, health check http://127.0.0.1:3000/healthz

claude mcp add --transport http alza http://127.0.0.1:3000/mcp

On HTTP the server is stricter than on stdio, because a network endpoint can be reached by more than one client:

  • Catalog only by default. Only the read-only, anonymous toolsets are usable: catalog (on) and pc_builder (enable with set_toolset). Every other toolset (auth, basket/checkout, account, orders/payments, reviews/subscriptions, chat, advanced_raw) is locked: list_toolsets shows it with the reason, and set_toolset refuses to enable it. These tools sign in to and act on a real Alza account (orders, payments, credentials), so a shared endpoint must not offer them by accident. Set ALZA_HTTP_ENABLE_ACCOUNT=1 to unlock them.

  • One server per MCP session. Each Mcp-Session-Id gets its own server instance: its own toolset state, OAuth tokens and one-time confirmation tokens. With ALZA_HTTP_ENABLE_ACCOUNT=1, each session also gets its own browser context and Chrome-fingerprint sidecar, because both keep Alza cookies. Sessions expire after 30 idle minutes.

  • No token file. ALZA_TOKEN_FILE (~/.alza-mcp/tokens.json) holds one person's login, so HTTP mode does not load it. Each session signs in with auth_start → auth_exchange. For a single-user localhost setup you can set ALZA_HTTP_ALLOW_TOKEN_FILE=1 (together with ALZA_HTTP_ENABLE_ACCOUNT=1); every session then starts signed in as that account, so never do this on a shared host. All sessions start from the same refresh token. Alza may rotate it on refresh (reported on 2026-09-10; a 2026-10-07 run saw the same refresh token come back six times, so treat rotation as possible, not guaranteed), in which case the first session that refreshes invalidates the copy the others hold (they then need auth_start → auth_exchange). Each session writes its refreshed tokens back to the token file, so a restart picks up the newest ones; keep to one active session in this mode. The same goes for the signed-in web session from --login: it is not loaded over HTTP unless you set ALZA_HTTP_ALLOW_WEB_SESSION=1, and then every session's catalog reads show that account's prices.

  • Localhost only by default. It binds 127.0.0.1 and rejects requests whose Host or Origin is not a loopback name (DNS-rebinding protection). There is no built-in authentication or TLS. If you bind elsewhere (--host 0.0.0.0), put it behind a reverse proxy that does both, and set ALZA_HTTP_ALLOWED_HOSTS.

Env var / flag

Default

Purpose

--http, ALZA_TRANSPORT=http

stdio

Serve over Streamable HTTP

--help, --version (-h, -v)

Print usage or the version and exit

--port N, ALZA_HTTP_PORT (or PORT)

3000

Listen port (0 picks a free one)

--host H, ALZA_HTTP_HOST

127.0.0.1

Bind address

ALZA_HTTP_ALLOWED_HOSTS

loopback names when bound to loopback, otherwise no check

Comma-separated hostnames accepted in Host/Origin

ALZA_HTTP_ENABLE_ACCOUNT

off

Unlock the auth/account/checkout/order/payment toolsets (per-session logins)

ALZA_HTTP_ALLOW_TOKEN_FILE

off

Also load ALZA_TOKEN_FILE into every session (single-user only; needs ALZA_HTTP_ENABLE_ACCOUNT)

ALZA_HTTP_ALLOW_WEB_SESSION

off

Load the --login web session (ALZA_WEB_SESSION_FILE) into the catalog browser (single-user only)

ALZA_HTTP_MAX_SESSIONS

50

Concurrent session cap (HTTP 503 beyond it)

ALZA_HTTP_SESSION_IDLE_MS

1800000

Close a session after this long without a request (a session holding an open GET/SSE stream is not closed)

ALZA_HTTP_REQUEST_TIMEOUT_MS

30000

Time a client has to send a whole request (headers get half); HTTP 408 beyond it. Responses, including tool calls and GET/SSE streams, are not limited

ALZA_HTTP_MAX_CONNECTIONS

256

Open TCP connection cap (SSE streams count); connections over it are dropped

Hosting is not supported yet. A hosted endpoint (Vercel mcp-handler, Fly, Railway, …) is a follow-up. The main obstacle is Cloudflare, not the transport: Alza is behind Cloudflare Bot Management, and both the headless browser and the curl_cffi sidecar get through it from a residential IP (live-verified) but are far more likely to be challenged from a datacenter IP. A hosted instance will probably need a residential proxy (ALZA_PROXY_URL) or a browser-as-a-service (for example Browserbase via ALZA_CDP_URL). The daily canary's GitHub-hosted runs show this: they get Cloudflare's interactive challenge. Other things a host needs: Chromium and Python with curl_cffi in the image, enough memory for one browser per account session, sticky routing (sessions live in one process's memory), and authentication in front of the endpoint. Keep the account toolsets locked on any multi-user host.


Pi agent integration

Register the local build in pi's global MCP config (~/.pi/agent/mcp.json):

{
  "alza": {
    "command": "node",
    "args": ["/absolute/path/to/alza-mcp-community/dist/index.js"]
  }
}

Run /reload (or mcp connect alza — the gateway respawns the stdio process, so a freshly built dist/ takes effect without /reload). The gateway exposes the tools (the domain tools plus list_toolsets/set_toolset/report_issue; only the catalog and auth toolsets are enabled until you call set_toolset) under the alza_ prefix (alza_search_products, alza_get_product, alza_cart, …). Auth auto-loads from ~/.alza-mcp/tokens.json. Verified in both modes: (a) in-session through the gateway — search/filter/detail, authenticated add-to-cart, bogus-coupon round-trip → server-side err:1 envelope (docs/live-evidence/pi-integration-2026-09-10.md); and (b) headless (pi -p one-shot prompt), where the agent discovers the alza_* tools, calls search_products with the right args, and reports the correct cheapest in-stock product (docs/live-evidence/headless-pi-2026-09-12.json); the 2026-09-13 re-run adds three more headless scenarios — catalog search with price-ascending sort, the authenticated account stack (account_status + cart), and the one-time mutation token flow (prepare_mutation) — all captured in docs/live-evidence/headless-pi-2026-09-13.json.


How it works

Alza has no public consumer API. This project reverse-engineers the Android app's REST surface (route names and DTOs recovered from the APK) and the website's own checkout pipeline. Neither is a supported or documented interface, so any of it can change or break without notice.

Cloudflare Bot Management. Alza sits behind it and returns HTTP 403 to plain HTTP clients. This server gets past it in two ways: a headless Chromium (catalog scraping) and a Chrome-fingerprint HTTP sidecar (scripts/cf-transport.py, using curl_cffi to impersonate Chrome's TLS/HTTP2 fingerprint) for the account/checkout API. That is circumvention of a bot-protection measure, which Alza's terms of use may prohibit. The sidecar and its setup script ship in the npm package, and postinstall tries to set up its curl_cffi venv. It stays optional: without Python or curl_cffi, the account stack (including OAuth sign-in) falls back to plain fetch and, for same-origin API calls, the browser. A request that changes something (POST/PUT/PATCH/DELETE) is only re-sent another way when the sidecar never sent it; if the sidecar fails after sending (timeout, connection error), the tool reports that the outcome is unknown instead of sending the order, payment or account change a second time. See the Disclaimer and SECURITY.md before using it.

Link attribution. Product, category and suggestion links that the catalog tools return (search_products, get_product, compare_products, recommend_alternatives, get_deals, autocomplete, list_categories, pc_build_*, watchdog_list and the alza://product/{code} resource) carry utm_source=alza-mcp-community&utm_medium=mcp, at Alza's request, so Alza can see visits that came through this server. The parameters are only added to Alza storefront links shown to you. The server's own requests to Alza, sign-in, payment, API, PDF and image URLs, and the account and checkout tools' raw responses are not tagged. No other data is added.

No generic arbitrary-route tool is exposed. What is and isn't covered:

  • Excluded: administrative login routes, telemetry/audit routes, device-token and anonymous-activity routes, and external payment hand-offs (Klarna, Google Pay) plus the quick-order payment family (documented as blocked in the coverage matrix).

  • Included, behind one-time tokens: order placement and cancellation, account registration, and credential/identity changes (password, 2FA, phone, email, account deletion — delete_account is irreversible).

  • Server-driven action URLs are followed only when returned by a confirmed response, through the origin-validated AppActionExecutor (GET/POST, path allowlist, a per-tool route family and method, a denylist of credential/payment/order and GET-write routes, sensitive-field blocklist, one-time confirmation token); they are not accepted as arbitrary MCP URLs.

The complete 12-family route inventory with method, DTO, prerequisites, side effects, exposure, and verification status is maintained in docs/mobile-endpoint-coverage.md.

The catalog tools still use the browser page adapter:

  • Search navigates /search.htm?exps=... and scrapes .browsingitem cards.

  • Product detail comes from page JSON-LD, with spec params from the page.

  • Reviews take the aggregate rating from JSON-LD and individual reviews from the mobile reviews API.

  • Pickup points combine branch data and geocoding.

  • Per-process caching remains enabled.

Image, font, and analytics requests are blocked at the route level. Catalog pages still load scripts, and sorted searches may fetch multiple result pages. Typical latencies: search ~2 s, product detail ~5 s warm.

┌────────────────────────────────────────────┐
│ stdio (default) or Streamable HTTP (--http)│
├────────────────────────────────────────────┤
│ MCP tools / resources / prompts            │
│  grouped into toolsets (toolsets.ts)       │
├────────────────────────────────────────────┤
│ Domain: catalog · reviews · pickup ·       │
│         deals · watchdog · pc-build ·      │
│         mobile-account (cart/checkout/…)   │
├────────────────────────────────────────────┤
│ Infra:                                     │
│  • browser (Playwright, CDP)               │
│  • impersonate-transport (curl_cffi        │
│    Chrome-fingerprint sidecar)             │
│  • mobile-api (APK-derived REST client)    │
│  • jsonld (schema.org parser)              │
│  • cache (LRU + TTL)                       │
│  • locale (multi-country)                  │
└────────────────────────────────────────────┘

For deeper architecture notes — including why there are two transports and why we don't ship the okhttp cookie recipe — see ARCHITECTURE.md.


Development

git clone https://github.com/lukabudik/alza-mcp-community.git
cd alza-mcp-community
npm install                 # dev checkout: postinstall is skipped on purpose
npm run setup:cf            # optional curl_cffi venv (needs bash + python3)
npx playwright install chromium --only-shell   # browser for live runs
npm test                    # unit tests, no network
npm run typecheck
npm run build               # → dist/
npm run eval                # agent-driven MCP eval harness (6 scenarios) → docs/live-evidence/
npm run validate:api        # hits real Alza — runs every read-only catalog tool (also the daily canary)
npm run pentest:app-action  # Node AppAction transport comparison
npm run live:endpoint-matrix # bounded read-only APK route matrix; requires ALZA_API_BASE_URL
npm run live:user-journeys   # catalog, delivery/cart, and anonymous-account journeys
npm run auth:login:py        # PKCE login step 1 (prints browser URL + pending-login.json)
npm run auth:exchange        # PKCE login step 2 (Node, needs a CF-friendly egress)
node scripts/e2e-order-payment.browser.mjs exchange "<pasted alza://identity redirect>"
                             # step 2 via Playwright (works even when Cloudflare challenges plain HTTP)
npm run live:e2e             # real order + after-order payment through the MCP tools
                             # (browser-backed transport; use ALZA_HEADLESS=false to watch it)
npm run live:e2e:node        # same journey over plain HTTP (in-memory MCP client); needs a
                             # non-challenged egress or a fresh ~/.alza-mcp/tokens.json
STOP_BEFORE_ORDER=1 npm run live:e2e   # dry run: stop right before order submission
ALLOW_ANON=1 STOP_BEFORE_ORDER=1 npm run live:e2e
                             # anonymous dry run; ALLOW_ANON alone does not prevent ordering
node dist/index.js          # run the server (waits for stdio MCP messages)
node dist/index.js --http   # or serve MCP Streamable HTTP on http://127.0.0.1:3000/mcp

Further reading:


Roadmap

main already covers catalog, filtering, cart, checkout, order placement/cancellation, account management, watchdogs and the PC builder (see What it does and the known limitations in docs/gap-analysis.md). Next up:

  • PC builder follow-ups and a hosted HTTP endpoint (follow-up to #16; local --http mode is shipped)

Priorities live in ROADMAP.md; everything is tracked in issues — good first issue is the place to start.


FAQ

Why the 92 MB Chromium download?

Alza's bot protection can challenge ordinary HTTP requests. The catalog uses headless Chromium to render product pages; the account stack can also use the optional Chrome-fingerprint sidecar, with browser-backed requests as a fallback. Chromium is installed by the postinstall hook or on first launch if needed. See How it works.

How are login and ordering protected?

  1. OAuth sign-in does not pass the Alza password as an MCP tool argument — sign-in happens in the user's browser (OAuth PKCE) and the MCP only exchanges the returned code. Tools that necessarily carry credentials as arguments (register, change_password, phone_change, email_change) require an explicit one-time token and should only be called with the user's direct instruction.

  2. checkout_preview creates a one-time confirmation token after the cart and delivery choice are reviewed; place_order refuses arbitrary tokens.

  3. web_place_order (the currently working submission path — mobile place_order returns HTTP 500 server-side) and every other high-impact mutation (cancel_order, pay_after_order, delete_account, …) require a one-time token from prepare_mutation. Tokens are single-use, bound to one action and to the exact arguments passed as payload, and expire after 5 minutes. MFA and 3-D Secure remain user-controlled browser interactions.

  4. These tools create, change and cancel real orders and accounts. The token is a guard against accidental calls by an agent, not a substitute for the user confirming the action — have your agent show the order summary and ask first.

Can I avoid the Chromium download?

Yes. Set ALZA_CDP_URL to your existing Chrome's debug port:

# launch Chrome with debugging
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222
# tell alza-mcp-community to attach
ALZA_MCP_SKIP_INSTALL=1 ALZA_CDP_URL=http://localhost:9222 npx alza-mcp-community

The MCP will use your Chrome — no separate download and faster cold starts. It opens its pages in a fresh browser context, so it does not use your Chrome's Alza cookies; for a signed-in catalog use --login (see Your own prices).

Will Alza take this down?

It might, and you should assume that's possible. The project has no commercial intent, caches to minimize traffic, and provides a takedown contact path via issues — if Alza requests removal, we'll comply. But it does get past Alza's bot protection (see How it works), so it is not a polite scraper by Alza's standards, and Alza's terms of use may forbid it. Use it for personal automation, not at scale.

How does this compare to rohlik-mcp?

tomaspavlin/rohlik-mcp is the inspiration. Differences:

  • Rohlik isn't behind a Cloudflare challenge → rohlik-mcp uses plain HTTP. We're forced to a real browser because Alza is.

  • Alza is a much larger catalog (millions of SKUs vs. a grocery list).

  • We cover the whole purchase path (cart, checkout, order placement and cancellation) plus account management, not only catalog reads, and group the tools into toolsets so only the catalog and auth toolsets are enabled by default.

  • We expose MCP resources and prompts in addition to tools.


Disclaimer

alza-mcp-community is not affiliated with, endorsed by, or sponsored by Alza.cz a.s. "Alza", "Alza.cz", and "AlzaBox" are trademarks of their respective owners.

What this software does. It is a reverse-engineered client. Its mobile-API routes and data shapes were recovered from the Alza Android application, and its catalog tools scrape alza.cz pages with a headless browser. To reach Alza's servers it circumvents Cloudflare Bot Management (headless Chromium plus a Chrome-fingerprint HTTP sidecar). The Android app's OAuth client credential, which is embedded in the public APK, is used as the default for the token exchange.

Legal. None of this is a published or supported interface, and Alza's terms of use may prohibit automated access, bot-protection circumvention and reverse engineering. Whether and how you may use this software depends on your jurisdiction and your agreement with Alza. You are solely responsible for that determination. This is not legal advice, and the maintainers make no representation that use of this software is lawful or permitted.

It acts on real accounts and spends real money. The checkout, order, payment, registration and account-deletion tools operate on live Alza accounts. Orders placed are real and binding; cancellation is not guaranteed to succeed. One-time tokens guard against accidental agent calls but are not a substitute for confirming each action yourself. Test only with accounts and orders you are prepared to lose, and never with credentials you are not prepared to expose to your agent's context.

No warranty. Provided "as is" under the MIT license. The maintainers make no guarantees of availability, accuracy, or fitness for any purpose, and are not liable for orders, charges, account lockouts or bans resulting from its use. The upstream interfaces can change without notice, so any tool may stop working. Do not rely on this for commercial decisions.

Security issues — see SECURITY.md. Alza employees or rights holders with concerns: please open an issue or contact the maintainers — we will respond promptly and comply with reasonable removal requests.


License

MIT. See LICENSE.

Contributors

A big thank you to Samuel Seidel, the project's first outside contributor and now a co-maintainer. He built the account, cart, checkout and order tools, toolsets, typed output schemas, category filtering and the live-verified test harness, which together took the project from a 5-tool catalog browser to a full shopping agent (#1, #5).

Thanks also to:

  • @jankryh, who tracked down why OAuth login never worked from the npm package and fixed it (#29, #30).

  • Peter Kizik, who made the API calls send the storefront's own country and language so alza.sk works, and brought get_deals to alza.sk with the lowest price a buyer can actually pay (#108, #113).

  • Martin Vlach, who enforced the request body size limit on existing HTTP sessions (#109).

  • Matúš Pohorenec, who fixed the curl_cffi venv setup in postinstall on Windows (#114).

  • @4sapp, who made the build scripts work on Windows (#106).

Contributions are welcome — see CONTRIBUTING.md and the open issues.

Acknowledgements

Available Tools

17 tools
account_statusCheck mobile API auth statusA
Read-onlyIdempotent

Report whether a mobile API access token is loaded in this server process. Use as a first check before account-scoped tools (cart, profile, order, add_to_cart), or to diagnose "not authenticated" failures. If no token is loaded, run auth_start, have the user complete the browser sign-in, then auth_exchange. Read-only; no network call.

Inputs: no named parameters. Returns: visitorId, apiBaseUrl, authenticated

auth_discoveryRead Alza OAuth discoveryA
Read-onlyIdempotent

Read the live OpenID Connect discovery document that the Alza mobile app uses (issuer, authorization endpoint, token endpoint). Use only when debugging the OAuth flow or verifying which identity endpoints Alza exposes before calling auth_start. Do not use for everyday shopping — it returns a configuration document, not account data, and changes nothing. Read-only; no credentials are ever sent.

Inputs: no named parameters. Returns: Raw OpenID Connect discovery document served by the Alza authority (issuer, aut…

auth_exchangeExchange Alza OAuth codeA

Complete the OAuth 2.0 PKCE sign-in: exchange the authorization code for mobile API tokens and load them into this server. Use immediately after the user finishes the auth_start flow in the browser. Pass the whole alza://identity?code=...&state=... redirect URL as code (state is then read from it), or the bare code plus state — never a password and never a refresh token here. Fails if the state does not match a pending auth_start session (start over from auth_start in that case). Side effect: replaces the token set currently loaded in this process; afterwards account tools such as cart, profile, and order are authenticated.

Inputs: code (required), state. Returns: Raw Alza envelope. err 0/1/113 (number; an HTML error-page string was observed…

auth_startStart Alza mobile API OAuthA

Start an OAuth 2.0 PKCE sign-in for the Alza mobile API: returns an authorization URL plus a state value. Use when account_status reports no loaded token, or when account tools start failing with authentication errors. Flow: open the returned authorization URL in a browser, sign in to Alza, the app redirects to alza://identity?code=...&state=... — then call auth_exchange with that redirect URL (or its code and this state). Desktop browsers cannot open the alza:// scheme, so the page appears to stall and after ~40 s shows "Při přihlášení došlo k chybě." — that message is a client-side timer, not a failed sign-in. Tell the user to open DevTools before signing in (Network tab with "Preserve log" on) and copy the alza://identity?code=... URL from the redirect's Location header, or from the Console error about failing to launch alza://. The code is short-lived, so exchange it promptly. This call only creates a local PKCE session: the user's credentials never enter the MCP and nothing changes on Alza's side. Do not call it repeatedly for one sign-in — each call supersedes the previous state.

Inputs: no named parameters. Returns: state, authorizationUrl

autocompleteAlza search suggestionsA
Read-onlyIdempotent

Cheap search-box suggestions (plain HTTP, no page render): suggested query phrases plus matching categories, brands and products with ids/codes. Use it to refine a messy Czech query before a full search_products — pass a category id as category_id, or a product code to get_product.

Inputs: query (required), limit. Returns: query, brands, articles, products, +2 more

compare_productsCompare products side by sideA
Read-onlyIdempotent

Fetch 2–6 products by their Alza codes (the code from search_products) and return one aligned comparison table: a column per product, rows for price, availability and rating, then every spec row present in any of them (exact spec-name matching; a product missing a row shows —). Use instead of calling get_product repeatedly when the user asks which of several candidates is better. A code that fails to load is reported in its own column (ok: false, error) while the others still compare. Pages load at most two at a time, so 6 products take roughly 15–30 s on a cold cache. Optional summarize: true adds a short verdict generated by your client's LLM via MCP sampling, grounded only in the table (skipped, not an error, when sampling is unsupported). Read-only.

Inputs: codes (required), summarize. Returns: rows, summary, products

find_pickup_pointsFind AlzaBox lockers and Alza showroomsA
Read-onlyIdempotent

Find AlzaBox parcel lockers and AlzaShop showrooms near a Czech/Slovak postal code: name, address, GPS, distance and opening hours, sorted nearest first. Use when the user asks where the nearest AlzaBox or Alza store is, or where they could pick up an order. No cart or login needed. Lockers come from Alza's public locker map and are cached; each has a parcelShopId. Locker hours vary (many are nonstop, mall lockers follow mall hours) and are looked up for the first 10 lockers returned. Important: a standalone locker list can't tell whether a given product fits. Alza excludes large items (observed: 34"+ monitors) from the whole AlzaBox network and routes them to a few oversized-item pickup points. To check a specific product, add it to the cart and read delivery_options (or web_pickup_places, which is cart-scoped). Read-only. Example: find_pickup_points({postal_code: '500 02', types: ['alzabox'], limit: 5})

Inputs: postal_code (required), limit, types, radius_km. Returns: points, warnings

get_dealsFind discounted Alza productsA
Read-onlyIdempotent

Find currently discounted products on Alza.cz, with current price, original price, savings and a discount % COMPUTED from the observed prices (never from marketing badges). Alza has no 'sale' facet or product-grid sale page, so this scans category listing pages (up to 3 pages ≈ 72 cards for a given category_id; page 1 of five popular categories when omitted) for cards showing a crossed-out original price or an 'Ušetříte' savings amount — it covers a bounded sample, not Alza's whole sale inventory (candidatesScanned says how many cards were checked). Czech store only (alza.cz price-box wording); errors on other locales. Prices are the shelf price, not code/AlzaPlus+ coupon prices. Read-only.

Inputs: limit, category_id, min_discount_percent. Returns: deals, total, categoryIds, candidatesScanned

get_productGet product detailsA
Read-onlyIdempotent

Fetch details for a single product by its Alza code (the code from search_products, e.g. 'WEXOA002B0' — not the numeric id): name, price (with the original price when discounted), availability, rating, brand, category, primary image, URL, and the spec table when the product page carries one (up to 30 rows, merged from both the DOM spec table and the JSON-LD additionalProperty list some page templates use instead — fixed 2026-09-27 after a product with only the latter returned no params at all). Use after search_products to compare shortlisted candidates in depth, and to get the canonical URL to show the user. For reviews use get_product_reviews; for the complete spec sheet (parameterGroups) use mobile_read with operation=router_product and product_id = the numeric d######## id from the product URL. Sourced from the product page's JSON-LD schema, so values are accurate and stable. Read-only.

Inputs: code (required). Returns: product

get_product_reviewsGet product reviewsA
Read-onlyIdempotent

Fetch reviews for a single product by its Alza code: the aggregate rating and review count plus up to limit individual reviews (author as Alza displays it, date, rating, body, pros/cons) from Alza's reviews API. Use after get_product when the user wants real-world feedback before deciding. If the reviews API is unavailable you receive the aggregate only (empty reviews array) — in that case rely on the rating/count. Do not use for the aggregate rating alone when you already have it from search_products/get_product. Read-only.

Inputs: code (required), limit. Returns: code, reviews, reviewCount, ratingAverage

list_categoriesList Alza categoriesA
Read-onlyIdempotent

Browse the Alza category tree one level at a time. Useful for narrowing a product search — find the right category id, then pass it to search_products as category_id. Without arguments, returns top-level categories.

Inputs: parent_id. Returns: categories

list_category_filtersList a category's filtersA
Read-onlyIdempotent

List the brands and attribute filters (facets) Alza defines for a category, with real ids and product counts. The attribute set differs per category (laptops have CPU/RAM facets, monitors have panel/resolution facets, …). Pass brands[].valueId to search_products as producer_ids (brand filtering works in every category), and filterable: true groups' param_id/value_id pairs as filters. Not every filterable facet is honoured by Alza — when one isn't, search_products returns an error rather than unfiltered results; drop that filter and compare candidates with get_product's params instead. Slider groups (filterMode: "range" — screen size, refresh rate, brightness, weight, port counts, …) filter by {param_id, min?, max?} in search_products's filters, with min/max in the facet's own units as given by values[].value (e.g. millimetres for a monitor diagonal, inches for a TV diagonal; live-verified 2026-10-06). filterable: false groups are informational only. Call this before using producer_ids/filters — never guess ids. Read-only.

Inputs: category_id (required). Returns: brands, groups, category_id

list_toolsetsList available toolsetsA
Read-onlyIdempotent

List every toolset this server groups its tools into: id, title, description, member tool names, and whether it's currently enabled. Only catalog and auth are enabled by default to keep the visible tool list small — use set_toolset to turn on the group a task actually needs (e.g. basket_and_checkout before placing an order). Call this first if you're unsure which toolset covers what you need. Read-only, no network call.

Inputs: no named parameters. Returns: toolsets

prepare_mutationPrepare an Alza mutationA
Read-only

Start a two-step mutation by returning a one-time confirmation token bound to exactly one action. This call itself sends nothing to Alza. Use it before the high-impact typed mutations — register (action register), address_upsert (address_create or address_edit), address_delete (address_delete), pay_after_order (after_order_payment), web_place_order (web_place_order), web_pay_after_order (web_after_order_payment), cancel_order (cancel_order), review_submit (review_submit), subscription_activate (subscription_activate), subscription_update_installment (subscription_update_installment), upload_attachment (attachment_upload), watchdog_set (watchdog_set), watchdog_delete (watchdog_delete) — and before any low-risk mutate_list action (create, rename, delete, add, remove, move, set_country, set_isic, add_gift, add_order_service, send_feedback, submit_discussion, rate_discussion, coupon_add, coupon_remove, basket_update, basket_unlock, gdpr_export). Pass the returned token as confirmation_token on the matching call; the token is single-use and only valid for the exact action you prepared. Do not use for read-only tools, and not for add_to_cart (which is a low-risk cart write that needs no token).

Inputs: action (required). Returns: action, confirmationToken

recommend_alternativesRecommend alternative productsA
Read-onlyIdempotent

Find alternatives to one product ("something like this but cheaper / better / same brand"). Candidate pool = Alza's own alternatives list for the product (mobile API, keyed by the numeric commodity id taken from the product URL); if that list is empty, or nothing in it survives the mode filter, falls back to a same-category search_products (poolSource says which was used). Heuristics: cheaper = strictly lower price, cheapest first; same-brand = brand match (source brand vs. the candidate's name), then rating desc, price asc; better-specs = rating >= source rating (unrated dropped), then rating desc, price asc — it ranks by customer rating, it does not compare spec tables, so shortlist then compare with get_product params. The source product is always excluded. Read-only.

Inputs: code (required), mode, limit. Returns: mode, source, poolSource, alternatives, +1 more

search_productsSearch Alza productsA
Read-onlyIdempotent

Search the Alza.cz catalog by keyword. Use this for product discovery — finding what's available, comparing options, or starting research. Returns a list with product code, name, price, stock (from the card's purchase CTA), and rating. To get full details for one product, follow up with get_product. Sorting: Alza's search page ignores server-side sort, so price-asc / price-desc / rating scan up to ~72 top-ranked candidates (3 pages) and sort them client-side — candidatesScanned reports how many were scanned; for an absolute price floor also pass max_price. in_stock: true keeps only products with a live purchase CTA. Brand/attribute filtering: call list_category_filters({category_id}) for real ids, then pass producer_ids and/or filters with category_id. This switches to Alza's own filtered category page, so query is ignored and results match what the website shows; a filter Alza doesn't honour returns an error rather than unfiltered results. Slider facets (screen size, refresh rate, brightness, weight, …) filter by {param_id, min?, max?} range; the applied ranges come back in appliedRanges. min_screen_inches/max_screen_inches use the category's real diagonal slider when category_id is given, and a product-name size heuristic otherwise. For attributes Alza has no facet for, compare shortlisted candidates with get_product's params. Read-only.

Inputs: query (required), page, sort, limit, +8 more. Returns: page, query, total, pageSize, +3 more

set_toolsetEnable or disable a toolsetA
Idempotent

Enable or disable every tool in one toolset (or all for every toolset) at once, so only the tools relevant to the current task are visible. Call list_toolsets first to see the available ids. Changing this fires the standard MCP tools-list-changed notification. No Alza-side effect — this only changes which tools this MCP server currently exposes to you.

Inputs: id (required), enabled (required). Returns: id, enabled, tools_affected

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 17 tools

    Disambiguation5/5

    Every tool targets a distinct purpose: search/discovery (search_products, autocomplete, list_categories, list_category_filters, get_deals), product detail (get_product, compare_products, get_product_reviews, recommend_alternatives), fulfillment (find_pickup_points), auth (auth_discovery, auth_start, auth_exchange, account_status), mutation gating (prepare_mutation), and meta toolset management (list_toolsets, set_toolset). The descriptions explicitly cross-reference each other (e.g. use compare_products instead of repeated get_product) so boundaries are clear.

    Naming Consistency4/5

    Predominantly consistent verb_noun snake_case (search_products, get_product, list_categories, compare_products, prepare_mutation). Minor deviations: find_pickup_points vs list_* for exploration, and auth_* / account_status / list_toolsets shift the noun order slightly. Still highly predictable.

    Tool Count3/5

    17 tools is borderline-heavy but defensible given the breadth (catalog, auth, cart/order, mutations, meta). The toolset-grouping mechanism exists precisely because the flat list is too large by default, which signals the count is on the high side.

    Completeness4/5

    Catalog-side coverage is strong (search, autocomplete, detail, compare, reviews, alternatives, deals, filters, categories, pickup). However the descriptions reference many tools that aren't visible in this set (cart, profile, order, add_to_cart, mutate_list, register, review_submit, watchdogs), so within the stated surface there are referenced-but-not-shown operations—a minor completeness gap for the catalog domain, largely mitigated by read-only coherent coverage.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI models to find the best online deals by browsing and interacting with multiple shopping platforms like Amazon and eBay across various regions. It uses Playwright to automate searches and retrieve product information from compatible e-commerce and deal-tracking websites.
      7 npm
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search Alza.cz's product catalog, retrieve details and reviews, and perform authenticated shopping actions such as managing carts, selecting delivery options, and placing orders through the Model Context Protocol.
      41
      3
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search grocery products, manage shopping carts, find deals, and review order, delivery, and account information across the Rohlik Group's grocery delivery platforms in several European countries. It supports switching between the Czech, German, Austrian, Hungarian, and Romanian storefronts via configuration.
      MIT