cdek

mcp-server-cdek

用于 API СДЭК v2 的 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