Alza MCP

alza-mcp-community

Let your AI agent shop on [Alza.cz](https://www.alza.cz) — Central Europe's largest e-commerce store.

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

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.

Real session, catalog toolset only, no account. Re-record: docs/demo-recording.md . Static version: docs/demo.svg .

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 is unofficial — 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

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- .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.

---

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:

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:

PC builder tools (enable pc_builder):

| `pc_build_check` | Checks a parts list (Alza codes).