# cdek-mcp [Health: Active]

**Category:** 📦 Delivery  
**Repository:** https://github.com/theYahia/cdek-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 174  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cdek-mcp

## Description
MCP server for CDEK delivery API — tariff calculation, order creation, tracking, cities, PVZ pickup

## Tools
Capabilities this server exposes over MCP:

- **calculate_tariff** — Расчёт стоимости и сроков доставки СДЭК по конкретному тарифу, маршруту и параметрам груза. Используйте для предварительной оценки перед созданием заказа. Требует код тарифа (136=склад-склад, 137=склад-дверь, 138=дверь-склад, 139=дверь-дверь). Для поиска кода города используйте get_cities.
- **calculate_tariff_list** — Расчёт стоимости доставки СДЭК по всем доступным тарифам для маршрута. Используйте когда нужно показать клиенту все варианты доставки с ценами и сроками, не зная заранее код тарифа.
- **create_order** — Создание заказа на доставку СДЭК с указанием отправителя, получателя и мест. Перед созданием рекомендуется рассчитать стоимость через calculate_tariff. После создания заказ можно отслеживать через get_order или track_shipment.
- **get_order** — Получение полной информации о заказе СДЭК по UUID. Возвращает статусы, номер накладной и детали доставки. Используйте после create_order для проверки обработки заказа.
- **delete_order** — Удаление заказа СДЭК по UUID. Работает только для заказов, ещё не переданных в курьерскую службу. После удаления заказ нельзя восстановить.
- **list_orders** — Поиск и фильтрация заказов СДЭК по дате, номеру ИМ или накладной СДЭК. Поддерживает пагинацию. Используйте для получения списка заказов за период или поиска конкретного заказа.
- **track_shipment** — Отслеживание отправления СДЭК по номеру накладной (cdek_number). Возвращает полную историю статусов с датами и городами. Если известен только UUID заказа — используйте get_order.
- **list_delivery_points** — Поиск пунктов выдачи (ПВЗ) и постаматов СДЭК по городу, индексу или GPS-координатам. При указании latitude+longitude+radius_km фильтрует и сортирует пункты по расстоянию. Возвращает адрес, время работы, наличие примерочной и способы оплаты.
- **get_cities** — Поиск городов в справочнике СДЭК по названию, индексу или стране. Возвращает код города, регион и ФИАС. Используйте для получения city_code перед вызовом calculate_tariff или create_order.
- **get_regions** — Получение справочника регионов СДЭК. Поддерживает фильтрацию по стране и названию региона, пагинацию. Используйте для построения иерархии локаций или фильтрации городов по региону.
- **generate_barcode** — Генерация штрихкода (этикетки) для заказа СДЭК по UUID. Поддерживает форматы A4, A5, A6 и до 10 копий. Ссылка на PDF появится в результатах get_order.
- **create_courier_pickup** — Создание заявки на вызов курьера СДЭК для забора отправления. Требует UUID заказа и временной интервал. После создания можно отслеживать статус заявки через get_courier_pickup.
- **get_courier_pickup** — Получение статуса заявки на вызов курьера СДЭК по UUID заявки. Возвращает дату, время и историю статусов заявки.
- **print_receipt** — Печать квитанции (накладной) для заказа СДЭК в формате PDF. Опрашивает API до готовности файла (до 10 секунд) и возвращает ссылку для скачивания.
- **create_webhook** — Подписка на вебхуки СДЭК для получения уведомлений о смене статуса заказов (ORDER_STATUS) или готовности фото (DOWNLOAD_PHOTO). СДЭК будет отправлять POST-запросы на указанный HTTPS URL.
- **delete_webhook** — Удаление подписки на вебхуки СДЭК по UUID вебхука. Используйте для отключения уведомлений или смены URL получателя (удалить старый + создать новый).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "cdek-mcp": {
    "command": "npx",
    "args": ["-y","@theyahia/cdek-mcp"],
    "env": {
      "CDEK_CLIENT_ID": "",
      "CDEK_CLIENT_SECRET": ""
    }
  }
}
```

**Requires environment variables:** `CDEK_CLIENT_ID`, `CDEK_CLIENT_SECRET` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What cdek-mcp MCP server does

The cdek-mcp MCP server exposes CDEK API v2 operations as MCP tools for an AI agent. It covers the main stages of a delivery workflow: estimate a shipment, identify locations and pickup points, create an order, monitor its status, arrange collection, and produce shipping documents.

Tariff tools calculate a price and delivery time for a selected tariff or return available tariff options for a route. Order tools create shipments, retrieve an order by UUID, cancel or delete an order, and search orders using dates, store numbers, or CDEK waybill numbers. Tracking uses a CDEK waybill number.

Geographic lookup includes cities, regions, pickup points, and parcel lockers. Pickup-point searches can use a city or GPS coordinates. The server also supports barcode or label generation, PDF receipts or waybills, courier pickup requests, and webhook subscriptions for order-status changes or delivery photos.

## How it works

The server communicates with CDEK through OAuth 2.0 using the client-credentials flow. It obtains an access token when the first API request is made, caches the token, refreshes it shortly before expiration, and shares one refresh operation across concurrent requests. If CDEK returns HTTP 401, the cached token is reset and the request is retried.

By default, the process can run as a standard local MCP command. It also supports Streamable HTTP mode. In HTTP mode, MCP JSON-RPC uses `POST /mcp`, the SSE stream is available at `GET /mcp`, and `DELETE /mcp` ends a session. `GET /health` provides a health endpoint.

## Setup and configuration

Install and launch the package with `npx -y @theyahia/cdek-mcp`, then provide credentials from the CDEK account’s integration settings. `CDEK_CLIENT_ID` and `CDEK_CLIENT_SECRET` are required. Set `CDEK_SANDBOX=true` to use the test endpoint; without it, the production CDEK endpoint is used. The public test credentials mentioned in the project may change, so dedicated sandbox credentials may be needed.

For HTTP mode, pass `--http` and set `HTTP_PORT`, for example `HTTP_PORT=3000 npx @theyahia/cdek-mcp --http`. The README includes configuration examples for Claude Desktop, Cursor, Windsurf, and VS Code.

## Tools and capabilities

The cdek-mcp MCP server provides 16 tools:

- `calculate_tariff` and `calculate_tariff_list` estimate delivery cost and time.
- `create_order`, `get_order`, `delete_order`, and `list_orders` manage shipments.
- `track_shipment` retrieves shipment tracking information.
- `get_cities`, `get_regions`, and `list_delivery_points` query CDEK geography and pickup locations.
- `generate_barcode` and `print_receipt` create shipment materials.
- `create_courier_pickup` and `get_courier_pickup` manage courier collection requests.
- `create_webhook` and `delete_webhook` manage event subscriptions.

## Limitations and notes

The server requires valid CDEK API credentials and depends on CDEK API availability. Sandbox behavior uses CDEK’s test environment and should be selected explicitly with `CDEK_SANDBOX=true`. Operations that create, cancel, or modify shipments require appropriate CDEK account permissions and should be tested before production use. The repository provides lint, type-checking, unit-test, build, and end-to-end smoke-test commands for local development.

_Full upstream README: https://allmcps.com/mcp/cdek-mcp/readme_