UPS MCP Server

A Model Context Protocol (MCP) server for UPS shipping and logistics capabilities. This server enables AI systems to seamlessly integrate with UPS API tools.

Users can integrate with the MCP server to allow AI agents to facilitate tracking events on their behalf, including tracking the status of a shipment, the latest transit screen, and expected delivery date and time. Agents will be authenticated using OAuth client credentials provided by the user after application creation on the UPS Developer Portal.

Usage

Prerequisites

• Obtain a Client ID and Client Secret: Create an application on the UPS Developer Portal to obtain your OAuth credentials – Client ID and Client Secret. (https://developer.ups.com/get-started?loc=en_US)
• Python 3.12 or higher
• Install uv (Python Package)

Environment Variables

• CLIENT_ID - UPS Client ID
• CLIENT_SECRET - UPS Client Secret
• ENVIRONMENT - Whether to point to Test (CIE) or Production (Accepted values: test, production)

Note: Your API credentials are sensitive. Do not commit them to version control. We recommend managing secrets securely using GitHub Secrets, a vault, or a password manager.

Execution

You can run the package using uvx:

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

To use an older version, you can specify the version number like so:

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

Popular Integrations

Here are sample config files for popular integrations. Different MCP Clients may require modification.

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 in 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"
      }
    }
  }
}

Available Tools

The server now supports the core international shipping workflow:

• validate_address — validates U.S. and Puerto Rico street addresses. UPS's Address Validation API is not a general international address validator; international destination data is supplied in the shipping/rating payload.
• rate_shipment — compares UPS services and charges. This is an estimate and does not purchase postage.
• get_time_in_transit — estimates transit time for an origin, destination, and package request.
• get_customs_requirements — obtains customs fields required by UPS.
• validate_customs_details — validates supplied customs data.
• estimate_landed_cost — estimates duties, taxes, and other landed-cost values returned by UPS.
• create_shipment — creates a shipment and returns UPS shipment/tracking and label data. This requires confirm=true and may incur charges.
• recover_label — recovers a label using the Shipping API contract.
• void_shipment — voids a shipment and requires confirm=true.
• rate_pickup — obtains a pickup estimate without scheduling one.
• create_pickup — schedules a pickup and requires confirm=true.
• get_pickup_status — checks pending pickup status for an account.
• cancel_pickup — cancels a pickup and requires confirm=true.
• find_pickup_service_centers — finds pickup facilities.
• get_pickup_political_divisions — gets pickup-valid political divisions for a country.
• customs_description_guidance — starts, continues, or submits feedback for an Export Assure interactive product-description and commodity/HTS guidance session using action=start|continue|feedback.
• submit_export_assure — submit cross-border shipment details for compliance guidance.
• upload_paperless_document, push_paperless_document_to_image_repository, and delete_paperless_document — manage UPS paperless customs/shipping documents. Deletion requires confirm=true.
• lookup_dangerous_goods_chemical_reference and dangerous_goods_acceptance_precheck — look up chemical data and run the UPS dangerous-goods acceptance audit pre-check.
• get_delivery_intercept_options — inspect post-shipment intercept eligibility or charges with action=eligibility|charges.
• apply_delivery_intercept — change delivery handling for an in-transit package with action=redirect|willcall|return|reschedule; requires confirm=true.
• cancel_delivery_intercept — cancel a prior intercept request; requires confirm=true.
• manage_tracking_alert_subscription — manage persistent Track Alert subscriptions with scope=package|account and action=subscribe|unsubscribe; requires confirm=true.
• find_ups_locations — find UPS Stores, Access Point locations, and other facilities.
• create_guaranteed_landed_cost_quote — request a guaranteed landed-cost quote when the UPS account has access to that product.
• track_package, track_by_reference, and track_shipment — track one package, reference-matched packages, or all packages in a shipment.

Complex UPS request bodies are accepted as validated JSON objects matching the request wrappers in ../api-documentation. This preserves support for international customs, service, packaging, and account fields that vary by UPS product while keeping the common MCP operation names stable.

For shipment billing, pass accountNumber to create_shipment or provide the equivalent UPS field in the request wrapper. The convenience argument is written to:

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

International customs declarations are sent in the UPS shipment wrapper's international-form fields (and can also be validated through validate_customs_details). A typical declaration contains one or more products/commodities with a plain-language description, quantity, unit value, currency, country of origin, and harmonized tariff/commodity code when known. Declared package value is represented separately through the package service options when required. The MCP does not guess tariff codes, values, or country of origin; missing or invalid customs data is returned by UPS for correction.

Recommended international workflow

1. Call rate_shipment and get_time_in_transit.
2. Call get_customs_requirements, then validate_customs_details.
3. Call estimate_landed_cost and review the returned duties, taxes, and warnings.
4. Review the complete shipment payload and call create_shipment with confirm=true only when the shipment should actually be created.
5. Track the returned tracking number with track_package or track_shipment.
6. Schedule a pickup separately with create_pickup and confirm=true.

UPS API-product approval, account permissions, production approval, service availability, and country-specific eligibility are controlled by UPS. A successful test-environment response does not prove that production shipping or pickup creation is enabled.