Skip to main content
Glama
README.md
# yerke-shops-mcp

A read-only [MCP](https://modelcontextprotocol.io) 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`).

## 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](https://nodejs.org) 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](#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:

```json
{
  "mcpServers": {
    "shops": {
      "command": "npx",
      "args": ["-y", "yerke-shops-mcp"],
      "env": { "KASPI_DEFAULT_CITY": "Павлодар" }
    }
  }
}
```

### Claude Code (CLI)

```bash
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:

```bash
claude mcp add --transport http shops https://your-host.example.com/mcp
```

### Claude in the browser (claude.ai)

Needs a [remote server](#hosting-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](#hosting-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

```bash
codex mcp add shops --env KASPI_DEFAULT_CITY=Павлодар -- npx -y yerke-shops-mcp
```

Or add it to `~/.codex/config.toml` yourself:

```toml
[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:

```json
{
  "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](#hosting-a-remote-server) URL; see Google's
[Gemini Apps developer mode](https://developers.google.com/connected-apps/mcp/dev-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

```bash
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

```bash
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

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