yerke-shops-mcp
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., "@yerke-shops-mcp Search Kaspi in Almaty for wireless earbuds and compare seller prices"
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.
yerke-shops-mcp
A read-only MCP server for browsing online marketplaces, so an AI assistant can help you find products more precisely. Currently supports Kaspi.kz (Kazakhstan).
It can search, read product details, compare seller prices, read reviews and look at photos. It cannot buy, order, add to cart or post reviews, and it needs no login or API key.
Tools
Tool | What it does |
| Supported marketplaces with a short description of each |
| Cities a marketplace supports, with optional name filter |
| Text search with paging, sorting, category/facet filters |
| Title, description, specifications |
| Seller prices and delivery options in a city |
| Rating summary and customer reviews |
| Product photos (URLs and embedded images) |
Every tool except list_marketplaces takes a marketplace argument (default kaspi).
Related MCP server: Taobao MCP Bridge
City
Kaspi prices, sellers and delivery depend on the city. Tools accept an optional city
(name, code or id — e.g. Алматы, almaty, 750000000), so you can simply tell the assistant
where you are. When no city is given the server uses the KASPI_DEFAULT_CITY environment
variable, and if that is unset, Павлодар.
Two ways to run it
Mode | Command | Used by |
Local (stdio) |
| Desktop apps and CLI agents, which start the server on your computer |
Remote (HTTP) |
| Browser chatbots, which can only reach a server at a public HTTPS URL |
Both need Node.js 18 or newer. npx downloads the package on first use,
so there is nothing to install by hand. Browser versions of Claude, ChatGPT and Gemini run in the
vendor's cloud and cannot start a program on your computer — for them, see
Hosting a remote server first.
Claude
Claude Desktop app
Open Settings → Developer → Edit Config and add the server to claude_desktop_config.json,
then restart the app:
{
"mcpServers": {
"shops": {
"command": "npx",
"args": ["-y", "yerke-shops-mcp"],
"env": { "KASPI_DEFAULT_CITY": "Павлодар" }
}
}
}Claude Code (CLI)
claude mcp add shops --env KASPI_DEFAULT_CITY=Павлодар -- npx -y yerke-shops-mcpRun /mcp inside Claude Code to check that it is connected. To use a hosted server instead:
claude mcp add --transport http shops https://your-host.example.com/mcpClaude in the browser (claude.ai)
Needs a remote server. Go to Settings → Connectors → Add custom
connector, give it a name and paste your https://…/mcp URL. No authentication is required.
A connector added this way is also available in the Claude mobile and desktop apps.
ChatGPT
ChatGPT in the browser and desktop app
ChatGPT accepts remote servers only, so this needs a remote server. Custom MCP servers are added through developer mode, which is available on paid plans:
Open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
Back in Apps & Connectors, choose Create, enter a name and your
https://…/mcpURL, and select No authentication.Enable the new connector in a chat.
OpenAI renames these screens from time to time; if the labels differ, look for "Connectors" or "Apps".
Codex CLI
codex mcp add shops --env KASPI_DEFAULT_CITY=Павлодар -- npx -y yerke-shops-mcpOr add it to ~/.codex/config.toml yourself:
[mcp_servers.shops]
command = "npx"
args = ["-y", "yerke-shops-mcp"]
env = { KASPI_DEFAULT_CITY = "Павлодар" }Gemini
Gemini CLI
Add the server to ~/.gemini/settings.json (all projects) or .gemini/settings.json (one project),
then restart Gemini CLI and run /mcp to check it:
{
"mcpServers": {
"shops": {
"command": "npx",
"args": ["-y", "yerke-shops-mcp"],
"env": { "KASPI_DEFAULT_CITY": "Павлодар" }
}
}
}For a hosted server use "httpUrl": "https://your-host.example.com/mcp" instead of command/args.
Gemini in the browser and apps
Support for custom MCP servers in the Gemini web app is limited and depends on account and region. Where it is offered, it takes a remote server URL; see Google's Gemini Apps developer mode documentation for the current steps. If it is not available to you, use Gemini CLI.
Other MCP clients
Any client that supports MCP works. For local use, configure the command npx with arguments
-y yerke-shops-mcp. For remote use, point the client at your server's /mcp URL
(Streamable HTTP transport).
Hosting a remote server
npx -y yerke-shops-mcp --http --host 0.0.0.0 --port 3000This serves MCP at http://<host>:3000/mcp (and a health check at /health). To use it from a
browser chatbot it must be reachable at a public HTTPS URL, so run it on a server or hosting
platform behind HTTPS (a reverse proxy such as Caddy or nginx, or the platform's built-in TLS).
For a quick trial from your own computer, an HTTPS tunnelling tool can expose the local port.
Option | Default | Meaning |
|
| Port to listen on |
|
| Address to bind; |
The remote server has no authentication: anyone who knows the URL can use it to browse the marketplace through your server. It only exposes public, read-only data, but keep the URL private if you do not want to share your server's capacity.
Example prompts
"Find a quiet robot vacuum under 150 000 ₸ in Astana and compare the top three by reviews."
"What do the negative reviews say about this laptop?"
"Show me photos of the cheapest iPhone 15 and tell me which seller delivers fastest."
Development
git clone https://github.com/Erkebulan-Akhmediya/yerke-shops-mcp.git
cd yerke-shops-mcp
npm install
npm run build
npm run smokenpm run smoke starts the server and calls every tool against the live marketplace.
Kaspi's API is undocumented and may change; run this first if something stops working.
Behind an HTTP proxy, run it with NODE_USE_ENV_PROXY=1 (Node 22.21+).
To add a marketplace, implement the Marketplace interface from src/types.ts in
src/marketplaces/ and register it in src/marketplaces/index.ts. Only marketplaces that can be
browsed without login are in scope.
Releasing
Bump the version (npm version patch), push the tag, and publish a GitHub release. The
Publish to npm workflow then publishes the package using the NPM_TOKEN repository secret.
To publish by hand instead: npm login, then npm publish --access public.
Notes
The server sends requests one at a time with a short gap and retries transient network errors.
How the Kaspi integration works is documented in
docs/kaspi-integration-notes.md.
License
MIT
Available Tools
7 toolsget_productGet product detailsARead-onlyIdempotent
Read one product: title, category, description, full specifications, photo count and link. For prices use get_product_offers, for photos get_product_photos, for reviews get_product_reviews.
Inputs: product_id (required), city, marketplace.
get_product_offersGet product prices and sellersARead-onlyIdempotent
List seller offers for a product in a city, cheapest first: seller, seller rating, price and delivery options. An empty list means the product is not available in that city.
Inputs: product_id (required), city, page, limit, +1 more.
get_product_photosGet product photosARead-onlyIdempotent
Get the product's gallery photos. Returns the photo URLs and, by default, the images themselves so they can be looked at directly. Set include_images=false to get only URLs.
Inputs: product_id (required), max_photos, marketplace, include_images.
get_product_reviewsGet product reviewsARead-onlyIdempotent
Read customer reviews of a product: rating summary plus review texts, pros/cons, helpful votes and links to customer photos. Filter by ALL, COMMENT (with text), PICTURE (with photos), POSITIVE or NEGATIVE.
Inputs: product_id (required), page, sort, limit, +2 more.
list_citiesList citiesARead-onlyIdempotent
List cities/towns supported by a marketplace, optionally filtered by a name fragment (Russian or English). Use it to find the right city value for the other tools.
Inputs: query, marketplace.
list_marketplacesList marketplacesARead-onlyIdempotent
List all supported online marketplaces with a short description of each (country, currency, languages, whether prices depend on city, supported sort options). Use the returned id as the marketplace argument of other tools.
Inputs: no named parameters.
search_productsSearch productsARead-onlyIdempotent
Search a marketplace for products by text and/or filters. Returns product cards (id, title, lowest price, rating, review count, link), the total count, and on request the available categories and facets whose value ids can be passed back in filters to narrow the search. Pages are 0-based.
Inputs: city, page, sort, query, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct resource: marketplace listing, city lookup, search, and three non-overlapping product sub-resources (offers, reviews, photos). Descriptions explicitly cross-reference siblings (e.g. get_product says to use get_product_offers for prices), eliminating guesswork between similar-sounding get_product_* tools.
Uniform snake_case verb_noun pattern throughout: list_marketplaces, list_cities, search_products, get_product, get_product_offers, get_product_reviews, get_product_photos. The get_product_* prefix cleanly groups the product sub-resources without ambiguity.
Seven tools is well within the ideal range and each earns its place, covering discovery, search, and the distinct facets of a product page. No redundant or filler tools are present.
The surface covers the full browsing lifecycle: marketplace/city resolution, filtered search with facets, product detail, offers/pricing, reviews, and photos. Minor gaps exist (no standalone category browsing or seller lookup, and no comparison tool), but search returns categories and facets so agents can work around them.
Maintenance
Related MCP Connectors
AI marketplace: search, buy, sell across Amazon, eBay, AliExpress. 13 tools.
Product search for AI shopping agents: prices and buy links from big retailers. No key needed.
AI-agent product catalog: search, lookup & purchase routing over verified merchant data.
Merchant product catalogs for AI agents: price, availability, specs, variants, buy links. Read-only.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables product search and retrieval from e-commerce APIs, returning markdown-formatted product listings with clickable links and prices for easy shopping assistance.18 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to search Taobao products, read details, and view product images through a local relay, with limited browsing and no ordering or cart actions.4MIT

datawebot MCP serverofficial
AlicenseNot gradedqualityBmaintenanceEnables AI agents to search products across online shops worldwide and retrieve each seller's price, shipping total, delivery note, rating, and direct product link.3MIT- AlicenseAqualityBmaintenanceEnables AI agents to search Snapp! Shop (snappshop.ir) products, compare every seller's offer in Toman, browse categories and brands, read buyer reviews, and catch flash sales — all read-only, with no login or API key required.1391 PyPI3MIT