{
  "markdown": "<!-- mcp-name: io.github.dontsovcmc/cdek -->\n\n# mcp-server-cdek\n\n[![Version](https://img.shields.io/badge/version-0.6.0-blue)](https://github.com/dontsovcmc/mcp-server-cdek)\n\nMCP-сервер, CLI-утилита и библиотека Pydantic-моделей для [API СДЭК v2](https://apidoc.cdek.ru/).\n\n- **MCP-сервер** — интеграция с Claude Code, Claude Desktop и другими MCP-клиентами\n- **CLI-утилита** — работа с API из терминала, скрипты и автоматизация\n- **Pydantic-модели** — типизированные модели API для использования в своих Python-программах\n\nВсе данные остаются на вашем компьютере — ключи никуда не передаются.\n\n## Оглавление\n\n- [Возможности](#возможности)\n- [MCP-сервер](#mcp-сервер)\n  - [Установка](#установка)\n  - [Подключение к Claude Code](#подключение-к-claude-code)\n  - [Подключение к Claude Desktop](#подключение-к-claude-desktop)\n  - [Подключение через --mcp-config](#подключение-через---mcp-config)\n  - [Примеры](#примеры-mcp)\n- [CLI-утилита](#cli-утилита)\n  - [Установка](#установка-cli)\n  - [Использование](#использование-cli)\n  - [Примеры команд](#примеры-команд)\n- [Pydantic-модели](#pydantic-модели)\n  - [Установка](#установка-библиотеки)\n  - [Использование в своих программах](#использование-в-своих-программах)\n- [Переменные окружения](#переменные-окружения)\n- [Разработка](#разработка)\n- [Лицензия](#лицензия)\n\n## Возможности\n\n### Доставка\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `cdek_create_order` | `create-order` | Создать заказ на доставку (от меня / ко мне, на ПВЗ / до двери) |\n| `cdek_track` | `track` | Отследить заказ по номеру СДЭК |\n| `cdek_barcode` | `barcode` | Скачать PDF штрихкода для заказа |\n| `cdek_label` | `label` | Скачать этикетку (A4/A5/A6/A7, по умолчанию A6 ~70x120мм) |\n| `cdek_waybill` | `waybill` | Скачать PDF накладной для заказа |\n| `cdek_delivery_points` | `delivery-points` | Поиск ПВЗ в городе |\n| `cdek_cities` | `cities` | Поиск городов СДЭК по названию |\n\n### Локальный справочник товаров\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `goods_list` | `goods list` | Список всех товаров |\n| `goods_add` | `goods add` | Добавить товар (название, вес, габариты, цена) |\n| `goods_remove` | `goods remove` | Удалить товар по названию |\n\nТовары хранятся локально в `~/.config/mcp-server-cdek/goods.json`. При создании заказа параметры берутся из справочника (если не указаны явно).\n\n### Настройки\n| Инструмент | CLI | Описание |\n|------------|-----|----------|\n| `config_show` | — | Показать текущую конфигурацию (отправитель, ПВЗ, дефолты товара) |\n| `config_set` | — | Установить значение конфигурации |\n\nНастройки хранятся в `~/.config/mcp-server-cdek/config.json`. Можно настроить через Claude: *«установи компанию-отправителя ООО Рога»*.\n\n---\n\n## MCP-сервер\n\n### Установка\n\n#### Шаг 1. Получить ключи API СДЭК\n\n1. Зарегистрируйтесь в [личном кабинете СДЭК](https://lk.cdek.ru)\n2. Перейдите в **Настройки** → **Интеграция**\n3. Скопируйте **Client ID** и **Client Secret**\n\n#### Шаг 2. Подключить MCP-сервер\n\n### Подключение к Claude Code\n\n**Способ 1: через uvx** (не требует установки пакета)\n\n> Требуется [uv](https://docs.astral.sh/uv/) — если не установлен:\n> ```bash\n> curl -LsSf https://astral.sh/uv/install.sh | sh\n> ```\n\n```bash\nclaude mcp add cdek \\\n  -e CDEK_CLIENT=ваш_client_id \\\n  -e CDEK_SECRET=ваш_client_secret \\\n  -- uvx mcp-server-cdek\n```\n\n**Способ 2: через pip**\n\n```bash\npip install mcp-server-cdek\n\nclaude mcp add cdek \\\n  -e CDEK_CLIENT=ваш_client_id \\\n  -e CDEK_SECRET=ваш_client_secret \\\n  -- python -m mcp_server_cdek\n```\n\nДанные отправителя настраиваются через Claude: *«установи отправителя: ООО Компания, Иванов И.И., ...»* → `config_set`. Также можно передать через env vars (см. ниже).\n\nДля удаления:\n```bash\nclaude mcp remove cdek\n```\n\n### Подключение к Claude Desktop\n\nДобавьте в конфигурационный файл:\n\n| Клиент | ОС | Путь к файлу |\n|--------|----|-------------|\n| Claude Code | все | `~/.claude/settings.json` (секция `mcpServers`) |\n| Claude Desktop | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Claude Desktop | Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Claude Desktop | Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n**Через uvx:**\n```json\n{\n  \"mcpServers\": {\n    \"cdek\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-cdek\"],\n      \"env\": {\n        \"CDEK_CLIENT\": \"ваш_client_id\",\n        \"CDEK_SECRET\": \"ваш_client_secret\"\n      }\n    }\n  }\n}\n```\n\n**Через pip** (после `pip install mcp-server-cdek`):\n```json\n{\n  \"mcpServers\": {\n    \"cdek\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_server_cdek\"],\n      \"env\": {\n        \"CDEK_CLIENT\": \"ваш_client_id\",\n        \"CDEK_SECRET\": \"ваш_client_secret\"\n      }\n    }\n  }\n}\n```\n\nОстальные настройки (отправитель, ПВЗ, дефолты товара) задаются через `config_set` или env vars (см. таблицу ниже).\n\n### Подключение через --mcp-config\n\nПодключает сервер только на время одной сессии Claude, не сохраняя в настройки. Токен хранится в отдельном `.env.mcp` файле, а не в конфиге Claude.\n\nИз JSON-строки:\n```bash\nclaude --mcp-config '{\"cdek\":{\"command\":\"bash\",\"args\":[\"-c\",\"source ~/.env.mcp && exec uvx mcp-server-cdek\"]}}'\n```\n\nИз файла:\n```bash\nclaude --mcp-config ~/mcp-servers.json\n```\n\nПример `~/mcp-servers.json`:\n```json\n{\n  \"cdek\": {\n    \"command\": \"bash\",\n    \"args\": [\"-c\", \"source ~/.env.mcp && exec uvx mcp-server-cdek\"]\n  }\n}\n```\n\nПример `~/.env.mcp`:\n```\nCDEK_CLIENT=ваш_client_id\nCDEK_SECRET=ваш_client_secret\n```\n\n#### Шаг 3. Проверить\n\nПопросите Claude: *«найди ПВЗ СДЭК в Москве на Тверской»* — он вызовет `cdek_delivery_points`.\n\n### Примеры (MCP)\n\n- «отправь посылку Иванову на ПВЗ MSK005, телефон +79001234567» → `cdek_create_order`\n- «отправь посылку до двери: Москва, Тверская 1, Петрову +79007654321» → `cdek_create_order`\n- «создай возвратный заказ от Сидорова, адрес: Самара, Ленина 10» → `cdek_create_order` (to_me)\n- «отследи посылку СДЭК 1234567890» → `cdek_track`\n- «скачай штрихкод для заказа 1234567890» → `cdek_barcode`\n- «скачай этикетку для заказа 1234567890» → `cdek_label`\n- «скачай этикетку A4 для заказа 1234567890» → `cdek_label` (format=A4)\n- «скачай накладную для заказа 1234567890» → `cdek_waybill`\n- «найди ПВЗ в Новосибирске» → `cdek_delivery_points`\n- «какие города СДЭК есть на \"Новосиб\"?» → `cdek_cities`\n- «добавь товар: Wi-Fi модем, 0.17 кг, 8x7x10 см» → `goods_add`\n- «список товаров» → `goods_list`\n\n---\n\n## CLI-утилита\n\n### Установка (CLI)\n\n```bash\npip install mcp-server-cdek\n```\n\nПеременные окружения `CDEK_CLIENT` и `CDEK_SECRET` обязательны:\n\n```bash\nexport CDEK_CLIENT=ваш_client_id\nexport CDEK_SECRET=ваш_client_secret\n```\n\nИли через файл:\n\n```bash\nmcp-server-cdek --env /path/to/.env <command>\n```\n\nФормат файла — `KEY=VALUE`, по одной переменной на строку, `#`-комментарии.\n\nДанные отправителя берутся из `~/.config/mcp-server-cdek/config.json` или переменных окружения.\n\n### Использование (CLI)\n\nБез аргументов запускается MCP-сервер, с командой — CLI. Все команды выводят JSON.\n\n```bash\n# Версия\nmcp-server-cdek --version\n\n# Справка\nmcp-server-cdek --help\nmcp-server-cdek <command> --help\n```\n\n### Примеры команд\n\n```bash\n# Создать заказ (от меня на ПВЗ)\nmcp-server-cdek create-order --direction from_me --name \"Петров Пётр\" --phone \"+79007654321\" --pvz MSK005\n\n# Создать заказ (от меня до двери)\nmcp-server-cdek create-order --direction from_me --name \"Петров Пётр\" --phone \"+79007654321\" --address \"Москва, Тверская 1\"\n\n# Создать возвратный заказ (ко мне)\nmcp-server-cdek create-order --direction to_me --name \"Сидоров\" --phone \"+79009876543\" --address \"Самара, Ленина 10\"\n\n# Отследить заказ\nmcp-server-cdek track 1234567890\n\n# Скачать штрихкод\nmcp-server-cdek barcode 1234567890 --output /tmp/barcode.pdf\n\n# Скачать этикетку (по умолчанию A6 ~70x120мм)\nmcp-server-cdek label 1234567890 --output /tmp/label.pdf\nmcp-server-cdek label 1234567890 --output /tmp/label_a4.pdf --format A4\n\n# Скачать накладную\nmcp-server-cdek waybill 1234567890 --output /tmp/waybill.pdf\n\n# Поиск ПВЗ\nmcp-server-cdek delivery-points Москва --search Тверская\n\n# Поиск городов\nmcp-server-cdek cities Новосиб\n\n# Справочник товаров\nmcp-server-cdek goods list\nmcp-server-cdek goods add --name \"Wi-Fi модем\" --weight 0.17 --height 8 --width 7 --length 10\nmcp-server-cdek goods remove --name \"Wi-Fi модем\"\n```\n\n---\n\n## Pydantic-модели\n\nПакет содержит типизированные Pydantic-модели всех объектов API СДЭК v2. Модели можно использовать в своих Python-программах для валидации данных и автодополнения в IDE.\n\n### Установка (библиотеки)\n\n```bash\npip install mcp-server-cdek\n```\n\n### Использование в своих программах\n\n```python\nfrom mcp_server_cdek.models import OrderRequest, TariffRequest, Location, Package, Item\n\n# Валидация данных из API\ndata = {\"tariff_code\": 136, \"from_location\": {\"code\": 44}, \"to_location\": {\"code\": 137}}\nreq = TariffRequest.model_validate(data)\nprint(req.tariff_code)  # type-safe доступ к полям\n\n# Создание объекта\nitem = Item(name=\"Товар\", ware_key=\"ART001\", weight=170, cost=1000, amount=1, payment={\"value\": 0})\nprint(item.model_dump_json())\n```\n\nВсе модели используют `extra=\"allow\"` для forward compatibility — неизвестные поля API не вызывают ошибок.\n\nПолный список моделей: [`models.py`](src/mcp_server_cdek/models.py)\n\n---\n\n## Переменные окружения\n\n| Переменная | Обязательная | По умолчанию | Описание |\n|------------|:------------:|:------------:|----------|\n| `CDEK_CLIENT` | да | — | Client ID из личного кабинета СДЭК |\n| `CDEK_SECRET` | да | — | Client Secret из личного кабинета СДЭК |\n| `CDEK_SENDER_COMPANY` | нет | — | Название компании отправителя |\n| `CDEK_SENDER_NAME` | нет | — | Краткое имя отправителя |\n| `CDEK_SENDER_FULL_NAME` | нет | — | Полное ФИО отправителя |\n| `CDEK_SENDER_EMAIL` | нет | — | Email отправителя |\n| `CDEK_SENDER_PHONE` | нет | — | Телефон отправителя |\n| `CDEK_MY_PVZ` | нет | — | Код вашего ПВЗ (для приёма посылок \"ко мне\") |\n| `CDEK_DEFAULT_PRODUCT_NAME` | нет | `Товар` | Название товара по умолчанию |\n| `CDEK_DEFAULT_WEIGHT` | нет | `0.17` | Вес по умолчанию в кг |\n| `CDEK_DEFAULT_HEIGHT` | нет | `8` | Высота по умолчанию в см |\n| `CDEK_DEFAULT_WIDTH` | нет | `7` | Ширина по умолчанию в см |\n| `CDEK_DEFAULT_LENGTH` | нет | `10` | Длина по умолчанию в см |\n| `CDEK_TIMEOUT` | нет | `30` | Таймаут HTTP-запросов к API (секунды) |\n| `CDEK_FILE_TIMEOUT` | нет | `60` | Таймаут скачивания файлов (секунды) |\n\nНастройки отправителя можно также задать через `config_set` — env vars имеют приоритет над конфиг-файлом.\n\n## Разработка\n\n```bash\npip install -e \".[test]\"\nruff check src/ tests/\npytest tests/ -v\n```\n\n## Лицензия\n\nMIT\n",
  "bytes": 10578,
  "sha": "41ce2136027bce76a5afcdf38ad05f400429f1a5575144d84d14f69ed01d17ef",
  "repo_slug": "dontsovcmc/mcp-server-cdek",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dontsovcmc_cdek_de9adab2/readme"
}