cdek-mcp

MCP-сервер для API доставки CDEK (v2). 16 инструментов охватывают весь цикл доставки: расчёт тарифов, управление заказами, отслеживание отправлений, поиск местоположений, вызов курьера, генерация штрихкодов/квитанций и вебхуки.

Инструменты (16)

Тарифы

Заказы

Отслеживание

Локации

Штрихкод и печать

Вызов курьера

Вебхуки

Related MCP server: Parcel MCP Server

Быстрый старт

Claude Desktop

~/.config/claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cdek": {
      "command": "npx",
      "args": ["-y", "@theyahia/cdek-mcp"],
      "env": {
        "CDEK_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "CDEK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "CDEK_SANDBOX": "true"
      }
    }
  }
}

Cursor / Windsurf

.cursor/mcp.json или .windsurf/mcp.json:

{
  "mcpServers": {
    "cdek": {
      "command": "npx",
      "args": ["-y", "@theyahia/cdek-mcp"],
      "env": {
        "CDEK_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "CDEK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "CDEK_SANDBOX": "true"
      }
    }
  }
}

VS Code (Copilot)

.vscode/mcp.json:

{
  "servers": {
    "cdek": {
      "command": "npx",
      "args": ["-y", "@theyahia/cdek-mcp"],
      "env": {
        "CDEK_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "CDEK_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "CDEK_SANDBOX": "true"
      }
    }
  }
}

Потоковый HTTP-транспорт

Для веб-развёртывания используйте флаг --http или переменную окружения HTTP_PORT:

HTTP_PORT=3000 npx @theyahia/cdek-mcp --http

Эндпоинты:

• POST /mcp — MCP JSON-RPC

• GET /mcp — SSE-поток

• DELETE /mcp — завершение сеанса

• GET /health — проверка работоспособности

Переменные окружения

Получите API-ключи: CDEK Dashboard > Интеграция > API-ключи.

Режим песочницы

Установите CDEK_SANDBOX=true, чтобы использовать тестовое окружение CDEK (api.edu.cdek.ru). В продакшене используется api.cdek.ru.

CDEK предоставляет общий sandbox-аккаунт для интеграционного тестирования:

• Client ID: EMscd6r9JnFiQ3bLoyjJY6eM78JrJceI

• Client Secret: PjLZkKBHEiLK3YsjtNrt3TGNG0ahs3kh

⚠️ CDEK время от времени перевыпускает этот общий тестовый аккаунт. Если вы получаете OAuth token error (HTTP 401) … invalid_client, публичная пара была заменена — запросите собственные sandbox-ключи в панели интеграции CDEK (lk.cdek.ru → Интеграция → API-ключи).

Аутентификация

Поток OAuth 2.0 Client Credentials, реализуемый классом OAuthStrategy из @theyahia/mcp-core:

• Автоматическое получение токена при первом запросе

• Кэширование токена с упреждающим обновлением незадолго до истечения срока действия

• Дедупликация параллельных запросов (один выполняющийся запрос на обновление токена используется совместно)

• Автоматический повтор при 401 с инвалидацией токена

Стек электронной коммерции

Используйте вместе с другими russian-mcp серверами для создания полного AI-стека электронной коммерции:

Часть серии russian-mcp.

Демо-запросы

1. «Сколько стоит отправить посылку весом 2 кг из Москвы в Санкт-Петербург?» Использует get_cities для поиска кодов городов, затем calculate_tariff_list для сравнения всех доступных тарифов.

2. «Найди ближайший пункт выдачи CDEK к Красной площади» Использует get_cities, чтобы определить city_code Москвы, затем list_delivery_points с latitude: 55.7539, longitude: 37.6208, radius_km: 5 — результаты фильтруются по радиусу и сортируются по расстоянию (каждый результат отмечен координаты и расстояние_км).

3. «Создай заказ на отправку книги из Казани в Новосибирск, запланируй вызов курьера и распечатай квитанцию» Использует create_order, затем create_courier_pickup для планирования забора, и print_receipt для накладной.

Разработка

git clone https://github.com/theYahia/cdek-mcp.git
cd cdek-mcp
npm install

npm run lint        # ESLint (flat config)
npm run typecheck   # tsc --noEmit
npm run build       # emit dist/
npm test            # unit tests (vitest)
npm run test:e2e    # e2e smoke test (lists tools, no real credentials)

Запустите сервер локально с CDEK sandbox (api.edu.cdek.ru) — используйте общую тестовую пару из раздела Режим песочницы или собственные sandbox-ключи:

CDEK_SANDBOX=true \
CDEK_CLIENT_ID=<YOUR_SANDBOX_CLIENT_ID> \
CDEK_CLIENT_SECRET=<YOUR_SANDBOX_CLIENT_SECRET> \
npm run dev

Смотрите CHANGELOG.md для примечаний к выпускам.

Лицензия

MIT