Skip to main content
Glama
cdek-shopping-mcp

cdek-shopping-mcp

by heahoh

cdek-shopping-mcp

An MCP server for the 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/ 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)

Related MCP server: Pyaterochka MCP Tool

Installation

Requires Python 3.11+ and uv.

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

{
  "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:

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

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

Available Tools

10 tools
catalog_categoriesA

List catalog categories, optionally the children of a given category.

Args:
    parent_id: ID of the parent category. Omit to get the top-level tree.

Inputs: parent_id.

get_productB

Get full details for a single product by ID.

Inputs: product_id (required).

get_product_summaryB

Get a short summary card for a product (for compact display/embedding).

Inputs: product_id (required).

list_category_productsB

List products inside a given catalog category.

Args:
    category_id: Category ID (see catalog_categories).
    sort: One of PRICE_ASC, PRICE_DESC, DEFAULT.
    page: Page number, 1-based.
    per_page: Results per page.

Inputs: category_id (required), page, sort, per_page.

list_collection_productsB

List products inside a given curated collection/subselection.

Args:
    collection_id: Collection ID.
    sort: One of PRICE_ASC, PRICE_DESC, DEFAULT.
    page: Page number, 1-based.
    per_page: Results per page.

Inputs: collection_id (required), page, sort, per_page.

list_ordersA

List the authenticated user's orders.

Requires the CDEK_SHOPPING_TOKEN environment variable to be set to a
valid bearer token; otherwise this returns an authentication error.

Inputs: no named parameters.

product_reviewsC

List customer reviews for a product.

Args:
    product_id: Product ID.
    has_media: If true, only reviews that include photos/video.
    has_text: If true, only reviews that include written text.
    page: Page number, 1-based.
    per_page: Reviews per page.
    sort_field: Field to sort by (e.g. date, rating).
    sort_order: Sort direction (asc/desc).

Inputs: product_id (required), page, has_text, per_page, +3 more.

recommendationsA

Get personalized/related product recommendations for given placements.

Args:
    placements: Required list of placement codes identifying where the
        recommendations will be shown (e.g. "product_page", "cart").
    product_id: Product IDs to base "related to this" recommendations on.
    category_id: Category ID to scope recommendations to.
    region_id: Region/location ID affecting availability and pricing.
    page: Page number, 1-based.
    per_page: Results per page.
    user_history: Opaque user-history token used to personalize results.

Inputs: placements (required), page, per_page, region_id, +3 more.

search_autocompleteB

Get search-box autocomplete suggestions for a partial query.

Args:
    q: Partial search text typed by the user.

Inputs: q (required).

search_productsA

Search products, brands and categories in the cdek.shopping catalog.

Args:
    q: Free-text search query, e.g. "Apple смартфон синий".
    filter: Facet filters as "key=value" strings (from a prior search response).
    sort: One of PRICE_ASC, PRICE_DESC, DEFAULT.
    page: Page number, 1-based.
    per_page: Results per page (max 100).
    only_filters: If true, return only the available filters, not results.

Inputs: q, page, sort, filter, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Enables AI assistants and MCP clients to search Pyaterochka stores, browse categories, find products with filters for price, brand, and promotions, and retrieve product details, store hours, and promotion conditions through the exposed MCP tools.
      12
      10
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables interaction with a Web Shop backend API through MCP, allowing users to browse products, create and view orders, and admins to manage all orders and users.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Turns an online store's catalog into MCP tools so agents can search products, fetch details, look up barcodes, analogs, categories, promotions and pickup points, and hand off a cart as a payment link rather than checking out. It is driven by a single TOML config with capability-based tool sets, bilingual model-facing texts, public catalog access plus OAuth 2.1-scoped personal tools like order history, and ready adapters for YML/Google Merchant feeds and WooCommerce across ten store engine presets.
      Apache 2.0