cdek

mcp-server-cdek

СДЭК v2 API用のMCPサーバー、CLIユーティリティ、Pydanticモデルライブラリです。

• MCPサーバー — Claude Code、Claude Desktop、その他のMCPクライアントとの連携
• CLIユーティリティ — ターミナルからのAPI操作、スクリプト、オートメーション
• Pydanticモデル — Pythonプログラムで使用するための、型付けされたAPIモデル

すべてのデータはお使いのコンピューターに保存され、キーが外部に送信されることはありません。

目次

• 機能
• MCPサーバー
  • インストール
  • Claude Codeへの接続
  • Claude Desktopへの接続
  • --mcp-configを使った接続
  • 使用例
• CLIユーティリティ
  • インストール
  • 使い方
  • コマンド例
• Pydanticモデル
  • ライブラリのインストール
  • プログラムでの使用方法
• 環境変数
• 開発
• ライセンス

機能

配送

ツール	CLI	説明
cdek_create_order	create-order	配送注文を作成します（自分から／自分宛て、受取拠点／ドアまで）
cdek_track	track	СДЭКの番号で注文を追跡します
cdek_barcode	barcode	注文のバーコードPDFをダウンロードします
cdek_label	label	ラベルをダウンロードします（A4/A5/A6/A7、既定はA6、約70x120мм）
cdek_waybill	waybill	注文の送り状PDFをダウンロードします
cdek_delivery_points	delivery-points	市内の受取拠点を検索します
cdek_cities	cities	名称でСДЭКの都市を検索します

ローカル商品カタログ

ツール	CLI	説明
goods_list	goods list	すべての商品を一覧表示します
goods_add	goods add	商品を追加します（名称、重量、寸法、価格）
goods_remove	goods remove	名称で商品を削除します

商品はローカルの~/.config/mcp-server-cdek/goods.jsonに保存されます。注文の作成時、明示的に指定されていない場合は、カタログからパラメーターが取得されます。

設定

ツール	CLI	説明
config_show	—	現在の設定を表示します（発送元、受取拠点、商品の既定値）
config_set	—	設定値を指定します

設定は~/.config/mcp-server-cdek/config.jsonに保存されます。Claudeを通じて設定できます：「発送元の会社をООО Рогаに設定して」。

---

MCPサーバー

インストール

ステップ1. СДЭК APIキーを取得する

1. СДЭКの個人アカウントに登録します
2. 設定 → 連携に移動します
3. Client IDとClient Secretをコピーします

ステップ2. MCPサーバーを接続する

Claude Codeへの接続

方法1：uvxを使う場合（パッケージのインストールは不要です）

uvが必要です。インストールされていない場合：

curl -LsSf https://astral.sh/uv/install.sh | sh

claude mcp add cdek \
  -e CDEK_CLIENT=ваш_client_id \
  -e CDEK_SECRET=ваш_client_secret \
  -- uvx mcp-server-cdek

方法2：pipを使う場合

pip install mcp-server-cdek

claude mcp add cdek \
  -e CDEK_CLIENT=ваш_client_id \
  -e CDEK_SECRET=ваш_client_secret \
  -- python -m mcp_server_cdek

発送元情報はClaudeを通じて設定します：「発送元を設定して：ООО Компания、Иванов И.И.、...」 → config_set。また、env varsで渡すこともできます（下記参照）。

削除するには：

claude mcp remove cdek

Подключение к Claude Desktop

Добавьте в конфигурационный файл:

Клиент	ОС	Путь к файлу
Claude Code	все	~/.claude/settings.json (секция mcpServers)
Claude Desktop	macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop	Windows	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop	Linux	~/.config/Claude/claude_desktop_config.json

Через uvx:

{
  "mcpServers": {
    "cdek": {
      "command": "uvx",
      "args": ["mcp-server-cdek"],
      "env": {
        "CDEK_CLIENT": "ваш_client_id",
        "CDEK_SECRET": "ваш_client_secret"
      }
    }
  }
}

Через pip (после pip install mcp-server-cdek):

{
  "mcpServers": {
    "cdek": {
      "command": "python",
      "args": ["-m", "mcp_server_cdek"],
      "env": {
        "CDEK_CLIENT": "ваш_client_id",
        "CDEK_SECRET": "ваш_client_secret"
      }
    }
  }
}

Остальные настройки (отправитель, ПВЗ, дефолты товара) задаются через config_set или env vars (см. таблицу ниже).

Подключение через --mcp-config

Подключает сервер только на время одной сессии Claude, не сохраняя в настройки. Токен хранится в отдельном .env.mcp файле, а не в конфиге Claude.

Из JSON-строки:

claude --mcp-config '{"cdek":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-cdek"]}}'

Из файла:

claude --mcp-config ~/mcp-servers.json

Пример ~/mcp-servers.json:

{
  "cdek": {
    "command": "bash",
    "args": ["-c", "source ~/.env.mcp && exec uvx mcp-server-cdek"]
  }
}

Пример ~/.env.mcp:

CDEK_CLIENT=ваш_client_id
CDEK_SECRET=ваш_client_secret

Шаг 3. Проверить

Попросите Claude: «найди ПВЗ СДЭК в Москве на Тверской» — он вызовет cdek_delivery_points.

Примеры (MCP)

• «отправь посылку Иванову на ПВЗ MSK005, телефон +79001234567» → cdek_create_order
• «отправь посылку до двери: Москва, Тверская 1, Петрову +79007654321» → cdek_create_order
• «создай возвратный заказ от Сидорова, адрес: Самара, Ленина 10» → cdek_create_order (to_me)
• «отследи посылку СДЭК 1234567890» → cdek_track
• «скачай штрихкод для заказа 1234567890» → cdek_barcode
• «скачай этикетку для заказа 1234567890» → cdek_label
• «скачай этикетку A4 для заказа 1234567890» → cdek_label (format=A4)
• «скачай накладную для заказа 1234567890» → cdek_waybill
• «найди ПВЗ в Новосибирске» → cdek_delivery_points
• «какие города СДЭК есть на "Новосиб"?» → cdek_cities
• «добавь товар: Wi-Fi модем, 0.17 кг, 8x7x10 см» → goods_add
• «список товаров» → goods_list

---

CLI-утилита

Установка (CLI)

pip install mcp-server-cdek

Переменные окружения CDEK_CLIENT и CDEK_SECRET обязательны:

export CDEK_CLIENT=ваш_client_id
export CDEK_SECRET=ваш_client_secret

Или через файл:

mcp-server-cdek --env /path/to/.env <command>

Формат файла — KEY=VALUE, по одной переменной на строку, #-комментарии.

Данные отправителя берутся из ~/.config/mcp-server-cdek/config.json или переменных окружения.

Использование (CLI)

Без аргументов запускается MCP-сервер, с командой — CLI. Все команды выводят JSON.

# Версия
mcp-server-cdek --version

# Справка
mcp-server-cdek --help
mcp-server-cdek <command> --help

Примеры команд

# Создать заказ (от меня на ПВЗ)
mcp-server-cdek create-order --direction from_me --name "Петров Пётр" --phone "+79007654321" --pvz MSK005

# Создать заказ (от меня до двери)
mcp-server-cdek create-order --direction from_me --name "Петров Пётр" --phone "+79007654321" --address "Москва, Тверская 1"

# Создать возвратный заказ (ко мне)
mcp-server-cdek create-order --direction to_me --name "Сидоров" --phone "+79009876543" --address "Самара, Ленина 10"

# Отследить заказ
mcp-server-cdek track 1234567890

# Скачать штрихкод
mcp-server-cdek barcode 1234567890 --output /tmp/barcode.pdf

# Скачать этикетку (по умолчанию A6 ~70x120мм)
mcp-server-cdek label 1234567890 --output /tmp/label.pdf
mcp-server-cdek label 1234567890 --output /tmp/label_a4.pdf --format A4

# Скачать накладную
mcp-server-cdek waybill 1234567890 --output /tmp/waybill.pdf

# Поиск ПВЗ
mcp-server-cdek delivery-points Москва --search Тверская

# Поиск городов
mcp-server-cdek cities Новосиб

# Справочник товаров
mcp-server-cdek goods list
mcp-server-cdek goods add --name "Wi-Fi модем" --weight 0.17 --height 8 --width 7 --length 10
mcp-server-cdek goods remove --name "Wi-Fi модем"

---

Pydantic-модели

Пакет содержит типизированные Pydantic-модели всех объектов API СДЭК v2. Модели можно использовать в своих Python-программах для валидации данных и автодополнения в IDE.

Установка (библиотеки)

pip install mcp-server-cdek

Использование в своих программах

from mcp_server_cdek.models import OrderRequest, TariffRequest, Location, Package, Item

# Валидация данных из API
data = {"tariff_code": 136, "from_location": {"code": 44}, "to_location": {"code": 137}}
req = TariffRequest.model_validate(data)
print(req.tariff_code)  # type-safe доступ к полям

# Создание объекта
item = Item(name="Товар", ware_key="ART001", weight=170, cost=1000, amount=1, payment={"value": 0})
print(item.model_dump_json())

Все модели используют extra="allow" для forward compatibility — неизвестные поля API не вызывают ошибок.

Полный список моделей: models.py

---

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

Переменная	Обязательная	По умолчанию	Описание
CDEK_CLIENT	да	—	Client ID из личного кабинета СДЭК
CDEK_SECRET	да	—	Client Secret из личного кабинета СДЭК
CDEK_SENDER_COMPANY	нет	—	Название компании отправителя
CDEK_SENDER_NAME	нет	—	Краткое имя отправителя
CDEK_SENDER_FULL_NAME	нет	—	Полное ФИО отправителя
CDEK_SENDER_EMAIL	нет	—	Email отправителя
CDEK_SENDER_PHONE	нет	—	Телефон отправителя
CDEK_MY_PVZ	нет	—	Код вашего ПВЗ (для приёма посылок "ко мне")
CDEK_DEFAULT_PRODUCT_NAME	нет	Товар	Название товара по умолчанию
CDEK_DEFAULT_WEIGHT	нет	0.17	Вес по умолчанию в кг
CDEK_DEFAULT_HEIGHT	нет	8	Высота по умолчанию в см
CDEK_DEFAULT_WIDTH	нет	7	Ширина по умолчанию в см
CDEK_DEFAULT_LENGTH	нет	10	Длина по умолчанию в см
CDEK_TIMEOUT	нет	30	Таймаут HTTP-запросов к API (секунды)
CDEK_FILE_TIMEOUT	нет	60	Таймаут скачивания файлов (секунды)

Настройки отправителя можно также задать через config_set — env vars имеют приоритет над конфиг-файлом.

Разработка

pip install -e ".[test]"
ruff check src/ tests/
pytest tests/ -v

Лицензия

MIT