UPS MCP Server

A Model Context Protocol server for UPS shipping and logistics APIs. Enables AI agents to create shipments, track packages, get rates, validate addresses, schedule pickups, and find UPS locations.

Install in your IDE

After installing, update the environment variables with your UPS Developer Portal credentials.

Tools

| Tool | Description | |------|-------------| | create_shipment | Create a shipment and generate a shipping label | | void_shipment | Cancel a shipment and void its label | | track_package | Track a package with full activity history | | get_rates | Get shipping rates for all available services | | get_time_in_transit | Get estimated delivery dates | | validate_address | Validate US/PR addresses | | schedule_pickup | Schedule a package pickup | | cancel_pickup | Cancel a scheduled pickup | | find_locations | Find nearby UPS stores and drop-off points |

Prerequisites

• Node.js 20+
• UPS Developer Portal credentials (Get started)
• UPS account number (for shipping and rating)

Installation

npx ups-mcp

Or install globally:

npm install -g ups-mcp

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | UPS_CLIENT_ID | Yes | OAuth Client ID from UPS Developer Portal | | UPS_CLIENT_SECRET | Yes | OAuth Client Secret | | UPS_ENVIRONMENT | No | sandbox (default) or production | | UPS_ACCOUNT_NUMBER | No | 6-digit UPS account (required for shipping/rating) |

Cursor

Add to .cursor/mcp.json:

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

Claude Desktop

Add to claude_desktop_config.json:

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

Usage Examples

Create a Shipment

"Ship a 5lb package from 123 Main St, Atlanta GA 30301 to 456 Oak Ave, Los Angeles CA 90001 via UPS Ground"

Get Rates

"What are the shipping rates for a 10lb package from NYC to Chicago?"

Track a Package

"Track package 1Z999AA10123456784"

Validate an Address

"Is 1600 Pennsylvania Ave NW, Washington DC 20500 a valid address?"

Schedule a Pickup

"Schedule a pickup tomorrow at 9am for 3 packages at our warehouse"

Development

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

Testing with MCP Inspector

npm run inspector

Running locally

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

Architecture

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

Security

Your API credentials are sensitive. Never commit them to version control. Use environment variables or a secrets manager.

Disclaimer

This project is an independent, unofficial, third-party tool. It is not affiliated with, endorsed by, sponsored by, or in any way officially connected to United Parcel Service, Inc. (UPS) or any of its subsidiaries.

"UPS" and the UPS brandmark are registered trademarks of United Parcel Service of America, Inc. All other trademarks are property of their respective owners. Use of these names is for identification and interoperability purposes only and does not imply endorsement.

This software is provided "AS IS", without warranty of any kind. You are solely responsible for:

• Complying with the UPS Technology Agreement and all applicable UPS terms of service, rate limits, and acceptable-use policies.
• Securing your API credentials and UPS account.
• All activity conducted through your UPS account via this tool.
• Compliance with all applicable laws and regulations in your jurisdiction.

The authors and contributors accept no liability for damages arising from the use of this software or the UPS APIs accessed through it.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT