UPS MCP Server

Сервер Model Context Protocol для API доставки и логистики UPS. Позволяет ИИ-агентам создавать отправления, отслеживать посылки, получать тарифы, проверять адреса, планировать вывоз и находить отделения UPS.

Быстрая установка

Добавьте в конфигурацию MCP (~/.cursor/mcp.json, .cursor/mcp.json или claude_desktop_config.json):

{
  "mcpServers": {
    "ups": {
      "command": "npx",
      "args": ["-y", "ups-mcp"],
      "env": {
        "UPS_CLIENT_ID": "your_client_id",
        "UPS_CLIENT_SECRET": "your_client_secret",
        "UPS_ACCOUNT_NUMBER": "123456",
        "UPS_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Получите свои учетные данные на портале разработчиков UPS.

Инструменты

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

• Node.js 20+

• Учетные данные портала разработчиков UPS (Начать работу)

• Номер счета UPS (для отправки и расчета стоимости)

Установка

npx ups-mcp

Или установите глобально:

npm install -g ups-mcp

Конфигурация

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

Примеры использования

Создание отправления

"Отправь посылку весом 5 фунтов с 123 Main St, Atlanta GA 30301 на 456 Oak Ave, Los Angeles CA 90001 через UPS Ground"

Получение тарифов

"Какие тарифы на доставку посылки весом 10 фунтов из Нью-Йорка в Чикаго?"

Отслеживание посылки

"Отследи посылку 1Z999AA10123456784"

Проверка адреса

"Является ли 1600 Pennsylvania Ave NW, Washington DC 20500 действительным адресом?"

Планирование вывоза

"Запланируй вывоз 3 посылок с нашего склада завтра в 9 утра"

Разработка

git clone https://github.com/roscoej/ups-mcp.git
cd ups-mcp
npm install
npm run build

Тестирование с помощью MCP Inspector

npm run inspector

Локальный запуск

cp .env.example .env
# Edit .env with your credentials
npm run build
node dist/index.js

Архитектура

src/
├── index.ts            # Entry point (stdio transport)
├── config.ts           # Environment variable resolution
├── server.ts           # MCP server factory
├── client/
│   ├── auth.ts         # OAuth 2.0 token manager
│   ├── http.ts         # HTTP client with retry + error handling
│   └── errors.ts       # Structured error types
├── tools/
│   ├── tracking.ts     # track_package
│   ├── shipping.ts     # create_shipment, void_shipment
│   ├── rating.ts       # get_rates, get_time_in_transit
│   ├── address.ts      # validate_address
│   ├── pickup.ts       # schedule_pickup, cancel_pickup
│   ├── locator.ts      # find_locations
│   ├── builders.ts     # Shared request payload builders
│   ├── constants.ts    # UPS API codes and enumerations
│   └── schemas.ts      # Zod input schemas
└── types/
    ├── config.ts       # Server configuration
    ├── shipping.ts     # Shipment types + service codes
    ├── tracking.ts     # Tracking types
    ├── rating.ts       # Rating types
    ├── address.ts      # Address validation types
    └── pickup.ts       # Pickup types

Безопасность

Ваши учетные данные API конфиденциальны. Никогда не добавляйте их в систему контроля версий. Используйте переменные окружения или менеджер секретов.

Отказ от ответственности

Этот проект является независимым, неофициальным сторонним инструментом. Он не связан, не одобрен, не спонсируется и каким-либо иным образом официально не относится к United Parcel Service, Inc. (UPS) или любой из ее дочерних компаний.

"UPS" и логотип UPS являются зарегистрированными товарными знаками United Parcel Service of America, Inc. Все остальные товарные знаки являются собственностью их соответствующих владельцев. Использование этих имен предназначено только для идентификации и обеспечения совместимости и не подразумевает одобрения.

Это программное обеспечение предоставляется "КАК ЕСТЬ", без каких-либо гарантий. Вы несете единоличную ответственность за:

• Соблюдение Соглашения о технологиях UPS и всех применимых условий обслуживания UPS, ограничений по количеству запросов и политик допустимого использования.

• Обеспечение безопасности ваших учетных данных API и учетной записи UPS.

• Все действия, выполняемые через вашу учетную запись UPS с помощью этого инструмента.

• Соблюдение всех применимых законов и нормативных актов в вашей юрисдикции.

Авторы и участники не несут ответственности за ущерб, возникший в результате использования этого программного обеспечения или API UPS, к которым осуществляется доступ через него.

Участие в разработке

Мы приветствуем вклад в проект! Пожалуйста, ознакомьтесь с CONTRIBUTING.md для получения инструкций.

Лицензия

MIT