Skip to main content
Glama

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

list_marketplaces

Supported marketplaces with a short description of each

list_cities

Cities a marketplace supports, with optional name filter

search_products

Text search with paging, sorting, category/facet filters

get_product

Title, description, specifications

get_product_offers

Seller prices and delivery options in a city

get_product_reviews

Rating summary and customer reviews

get_product_photos

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)

npx -y yerke-shops-mcp

Desktop apps and CLI agents, which start the server on your computer

Remote (HTTP)

npx -y yerke-shops-mcp --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-mcp

Run /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/mcp

Claude 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:

  1. Open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.

  2. Back in Apps & Connectors, choose Create, enter a name and your https://…/mcp URL, and select No authentication.

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

Or 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 3000

This 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 <n>

$PORT or 3000

Port to listen on

--host <addr>

127.0.0.1

Address to bind; 0.0.0.0 accepts outside connections

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 smoke

npm 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 tools
get_productGet product detailsA
Read-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 sellersA
Read-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 photosA
Read-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 reviewsA
Read-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 citiesA
Read-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 marketplacesA
Read-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 productsA
Read-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

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      13
      91 PyPI
      3
      MIT