cdek-shopping-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., "@cdek-shopping-mcp search for wireless headphones and show reviews for the top result"
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.
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 |
| List catalog categories / subcategories |
| Search products, brands and categories |
| Search-box autocomplete suggestions |
| Full product details by ID |
| Compact product summary card |
| Customer reviews for a product |
| Products inside a catalog category |
| Products inside a curated collection |
| Personalized/related product recommendations |
| 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 syncUse 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-mcpConfiguration
All configuration is via environment variables, all optional:
Variable | Default | Purpose |
|
| API base URL |
| (none) | Bearer token for authenticated endpoints (e.g. |
|
|
|
|
| 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 inspectorLicense
MIT
Available Tools
10 toolscatalog_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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Search multi-merchant supply, checkout, and track orders via MCP.
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.
E-commerce MCP gateway: live product deals, attributed buy links, order tracking, flights.
Unofficial Shopify MCP Pack — wraps the Shopify Admin REST API (2024-01)
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables querying and comparing prices, availability, ratings, reviews, and seller details from major Russian and Chinese marketplaces (Wildberries, Ozon, Yandex Market, and others) without requiring API keys, via a unified MCP interface.2425MIT
- AlicenseCqualityDmaintenanceEnables 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.1210MIT
- FlicenseNot gradedqualityCmaintenanceEnables 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.-
- AlicenseNot gradedqualityBmaintenanceTurns 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