UPS MCP Server

Сервер Model Context Protocol (MCP) для возможностей доставки и логистики UPS. Этот сервер позволяет ИИ-системам бесшовно интегрироваться с инструментами UPS API.

Пользователи могут подключить MCP-сервер, чтобы ИИ-агенты выполняли отслеживание событий от их имени, включая отслеживание статуса отправления, последнего экрана транзита, а также ожидаемых даты и времени доставки. Агенты будут аутентифицированы с помощью OAuth-учётных данных клиента, предоставленных пользователем после создания приложения на портале разработчика UPS.

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

Предварительные требования

• Получите Client ID и Client Secret: создайте приложение на портале разработчика UPS, чтобы получить учётные данные OAuth — Client ID и Client Secret. (https://developer.ups.com/get-started?loc=en_US)

• Python 3.12 или выше

• Установите uv (менеджер Python-пакетов)

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

• CLIENT_ID — идентификатор клиента UPS (Client ID)

• CLIENT_SECRET — секрет клиента UPS (Client Secret)

• ENVIRONMENT — определяет, использовать ли тестовую среду (CIE) или производственную (Production). Допустимые значения: test, production

Примечание: ваши учётные данные API являются конфиденциальными. Не сохраняйте их в системе контроля версий. Мы рекомендуем безопасно управлять секретами с помощью GitHub Secrets, хранилища или менеджера паролей.

Выполнение

Вы можете запустить пакет с помощью uvx:

uvx --from git+https://github.com/VoxveyAI/UPS-MCP ups-mcp

Чтобы использовать более старую версию, укажите номер версии следующим образом:

uvx --from git+https://github.com/VoxveyAI/UPS-MCP@v1.0.0 ups-mcp

Related MCP server: UPS MCP Server

Популярные интеграции

Ниже приведены примеры файлов конфигурации для популярных интеграций. Разные MCP-клиенты могут требовать доработок.

Claude Desktop

{
  "mcpServers": {
    "ups-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/VoxveyAI/UPS-MCP", "ups-mcp"],
      "env": {
        "CLIENT_ID": "**********",
        "CLIENT_SECRET": "**********",
        "ENVIRONMENT": "test"
      }
    }
  }
}

GitHub Copilot в VS Code

{
  "servers": {
    "ups-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/VoxveyAI/UPS-MCP", "ups-mcp"],
      "env": {
        "CLIENT_ID": "**********",
        "CLIENT_SECRET": "**********",
        "ENVIRONMENT": "test"
      }
    }
  }
}

Доступные инструменты

Сервер теперь поддерживает основной международный рабочий процесс доставки:

• validate_address — проверяет адреса улиц в США и Пуэрто-Рико. API Address Validation в UPS не является универсальным международным валидатором адресов; данные о международном месте назначения передаются в полезной нагрузке shipping/rating.

• rate_shipment — сравнивает услуги и тарифы UPS. Результат является оценкой и не оплачивает пересылку.

• get_time_in_transit — оценивает время в пути для запроса с указанием места отправления, назначения и параметров посылки.

• get_customs_requirements — получает поля таможенных данных, требуемые UPS.

• validate_customs_details — проверяет предоставленные таможенные данные.

• estimate_landed_cost — оценивает пошлины, налоги и другие составляющие общую стоимость (landed cost), возвращаемые UPS.

• create_shipment — создаёт отправление и возвращает данные отправления, номер отслеживания и этикетку. Требуется confirm=true; это может повлечь расходы.

• recover_label — восстанавливает этикетку по контракту Shipping API.

• void_shipment — аннулирует отправление; требуется confirm=true.

• rate_pickup — получает оценку забора без назначения самого забора.

• create_pickup — назначает забор; требуется confirm=true.

• get_pickup_status — проверяет статус ожидающего забора для учётной записи.

• cancel_pickup — отменяет забор; требуется confirm=true.

• find_pickup_service_centers — находит центры обслуживания забора.

• get_pickup_political_divisions — получает административные единицы страны, в которых разрешён забор.

• customs_description_guidance — запускает, продолжает или отправляет обратную связь в интерактивном сеансе Export Assure с описаниями товаров и указаниями по товарной позиции/HTS с помощью action=start|continue|feedback.

• submit_export_assure — отправляет сведения о трансграничной доставке для рекомендаций по соответствию.

• upload_paperless_document, push_paperless_document_to_image_repository и delete_paperless_document — управление безбумажными таможенными и транспортными документами UPS. Удаление требует confirm=true.

• lookup_dangerous_goods_chemical_reference и dangerous_goods_acceptance_precheck — поиск данных о химических веществах и предварительна проверка приёмки опасных грузов UPS.

• get_delivery_intercept_options — проверка права на перехват доставки после отправки либо выраженных сверх неё расходов с помощью action=eligibility|charges.

• apply_delivery_intercept — изменяет обработку доставки для посылки в пути с помощью action=redirect|willcall|return|reschedule; требуется confirm=true.

• cancel_delivery_intercept — отменяет ранее поданный запрос на перехват; требуется confirm=true.

• manage_tracking_alert_subscription — управляет постоянными подписками Track Alert с помощью scope=package|account и action=subscribe|unsubscribe; требуется confirm=true.

• find_ups_locations — находит отделения UPS Store, точки доступа Access Point и другие объекты.

• create_guaranteed_landed_cost_quote — запрашивает гарантированную смету landed cost, если учётная запись UPS имеет доступ к этому продукту.

• track_package, track_by_reference и track_shipment — отслеживают одну посылку, посылки, совпавшие по ссылке, или все посы внутри отправления.

Сложные тела запросов UPS принимаются как, проверенные JSON-данные, соответствующие обёрткам запросов в ../api-documentation. Это сохраняет подднимание международных таможенных, сервисных, упаковочных и учётных полек, которые отличаются в зависимости от продукта UPS, при сохранении стабильных общих имён операций MCP.

Для оплаты отправления передайте accountNumber в create_shipment или оставьте эквивалентное поле UPS в общем обёртке запроса. Значение этого удобного аргумента записывается в:

{
  "ShipmentRequest": {
    "Shipment": {
      "PaymentInformation": {
        "ShipmentCharge": {
          "BillShipper": {"AccountNumber": "YOUR_UPS_ACCOUNT_NUMBER"}
        }
      }
    }
  }
}

Международные таможенные декларации передаются в поля в international-form в обёртке отправления UPS (их также можно проверить через validate_customs_details). Обычная декларация содержиas contain содержит один или несколько товаров/номенклатур с описанием на обычном языке, количество, стоимость единицы, валюту, страну происхождения и код тарифной/товарной позиции, если известен. Заявленная стоимость посылки указывается отдельно в параметрах услуг для посылки и при необходимости. The MCP не угадывает таможенные коды, стоимости или страну происхождения; неполные или некорректные таможенные данные возвращаются UPS для исправления.

Рекомендуемый порядок действий для международной отправки

1. Вызовите rate_shipment и get_time_in_transit.

2. Вызовите get_customs_requirements, затем validate_customs_details.

3. Вызовите estimate_landed_cost и проанализируйте возвращённые пошлины, налоги и предупреждения.

4. Просмотрите полную полезную нагрузку отправления и вызывайте create_shipment с confirm=true только тогда, когда отправление действительно должно быть создано.

5. Отслеживайте полученный номер отслеживания с помощью track_package или track_shipment.

6. Закажите отслеживание по отдельности через create_pickup и confirm=true.

Одобрение продуктов API UPS, права учётной записи, одобрение для production-среды, доступность услуг и страновые разрешения контролируются UPS. Успешный ответ тестовой среды не подтверждает, что производственная отправка или создание забора включены.