Skip to main content
Glama
cdek-shopping-mcp

cdek-shopping-mcp

by heahoh
README.md
# cdek-shopping-mcp

An [MCP](https://modelcontextprotocol.io) server for the [cdek.shopping](https://cdek.shopping) storefront API. It exposes catalog browsing, search, product details, reviews and recommendations as tools an MCP client (Claude, Claude Code, etc.) can call.

This is an early, read-focused release. More endpoints/tools (orders, cart, etc.) will be added over time — see [specs/](specs) for the full raw API surface this server can grow into.

## Tools

| Tool | Description |
| --- | --- |
| `catalog_categories` | List catalog categories / subcategories |
| `search_products` | Search products, brands and categories |
| `search_autocomplete` | Search-box autocomplete suggestions |
| `get_product` | Full product details by ID |
| `get_product_summary` | Compact product summary card |
| `product_reviews` | Customer reviews for a product |
| `list_category_products` | Products inside a catalog category |
| `list_collection_products` | Products inside a curated collection |
| `recommendations` | Personalized/related product recommendations |
| `list_orders` | List the authenticated user's orders (requires a token) |

## Installation

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/heahoh/cdek-shopping-mcp.git
cd cdek-shopping-mcp
uv sync
```

### Use with an MCP client

Add to your client's MCP server config (e.g. Claude Desktop/Code `mcp.json`):

```json
{
  "mcpServers": {
    "cdek-shopping": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/cdek-shopping-mcp", "run", "cdek-shopping-mcp"]
    }
  }
}
```

Or, once published, run it directly from GitHub with `uvx`:

```bash
uvx --from git+https://github.com/heahoh/cdek-shopping-mcp cdek-shopping-mcp
```

## Configuration

All configuration is via environment variables, all optional:

| Variable | Default | Purpose |
| --- | --- | --- |
| `CDEK_SHOPPING_BASE_URL` | `https://api.cdek.shopping/front-controller/v1` | API base URL |
| `CDEK_SHOPPING_TOKEN` | _(none)_ | Bearer token for authenticated endpoints (e.g. `list_orders`) |
| `CDEK_SHOPPING_LANG` | `ru` | `Accept-Language` header sent on every request |
| `CDEK_SHOPPING_MAX_RPS` | `5` | Max requests/second enforced by the client |

## Rate limiting

cdek.shopping asked that these endpoints never be called at more than 5
requests/second. The client throttles every call to this rate regardless of
how many tools an agent fires concurrently, and the server advertises the
limit to MCP clients via its `instructions`. Agents should still avoid
redundant lookups and back off on errors rather than retrying immediately.

## Development

```bash
uv sync
uv run cdek-shopping-mcp          # run the server over stdio
uv run mcp dev src/cdek_shopping_mcp/server.py  # run with the MCP inspector
```

## License

MIT

TDQS

B3.4/5.0

Scored across 10 tools

Disambiguation4/5

Most tools target distinct resources or retrieval modes: catalog browsing, product search, product details, reviews, recommendations, and orders. Minor overlap exists between get_product and get_product_summary, and between search_products and the category/collection product listers, but the descriptions make the boundaries reasonably clear.

Naming Consistency3/5

Several tools follow a readable verb_noun pattern, such as list_orders, search_products, get_product, and list_category_products. However, catalog_categories, product_reviews, and recommendations are noun-only names, and search_autocomplete slightly breaks the resource-action pattern, producing mixed conventions.

Tool Count5/5

Ten tools is well-scoped for a shopping/catalog MCP server, covering search, category browsing, product details, reviews, recommendations, and order listing. Each tool has a plausible role and the set does not feel bloated.

Completeness3/5

The catalog side is fairly complete: categories, search, product details, reviews, collections, and recommendations are covered. The shopping lifecycle is not: there is no get_order detail tool, no cart operations, and no checkout or purchase flow, which are notable gaps for a shopping-oriented server.

Maintenance

ActivityMaintained
ResponsivenessOutdated data