Cdek MCP README

MCP-сервер для СДЭК API — 16 инструментов для ИИ-агента: тарифы, заказы, трекинг

Если вы искали, как подключить доставку СДЭК к Claude или другому ИИ-агенту, — этот сервер закрывает весь цикл отправления через CDEK API v2: расчёт тарифов и сроков, создание и отмена заказов, трекинг по накладной, поиск городов и пунктов выдачи, вызов курьера, штрихкоды и квитанции, вебхуки. Спрашиваете «сколько стоит и как долго везти 2 кг из Москвы в Казань» — получаете сравнение тарифов таблицей, а не форму на сайте. Работает и на тестовом контуре СДЭК, и на боевом.

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

Тарифы

Заказы

Трекинг

География

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

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

Вебхуки

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

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"
      }
    }
  }
}

Транспорт Streamable 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: личный кабинет СДЭК → Интеграция → Ключи API.

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

Задайте CDEK_SANDBOX=true, чтобы работать с тестовым контуром СДЭК (api.edu.cdek.ru). Боевой контур — api.cdek.ru.

СДЭК публикует общий тестовый аккаунт для интеграционных проверок:

• Client ID: EMscd6r9JnFiQ3bLoyjJY6eM78JrJceI
• Client Secret: PjLZkKBHEiLK3YsjtNrt3TGNG0ahs3kh

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

Авторизация

OAuth 2.0, поток Client Credentials, реализован в OAuthStrategy из @theyahia/mcp-core:

• Токен запрашивается автоматически при первом обращении
• Кэширование токена с упреждающим обновлением незадолго до истечения
• Дедупликация параллельных запросов (одно обновление токена делится между всеми)
• Автоматический повтор на 401 со сбросом токена

E-commerce-стек

Соберите полный ИИ-стек для интернет-магазина вместе с другими серверами WWmcp:

Часть серии WWmcp.

Демо-промпты

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

2. «Найди ближайший пункт выдачи СДЭК к Красной площади» Использует 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       # сборка в dist/
npm test            # юнит-тесты (vitest)
npm run test:e2e    # e2e smoke-тест (перечисляет инструменты, без реальных ключей)

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

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

Заметки о релизах — в CHANGELOG.md.

Лицензия

MIT

Часть WWmcp · Telegram: @vhodvai