# 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
```json
{
  "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
```json
{
  "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:

```json
{
  "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.