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.

Quick Install

Add to your MCP config (~/.cursor/mcp.json, .cursor/mcp.json, or 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"
      }
    }
  }
}

Get your credentials at the UPS Developer Portal.

Tools

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

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