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

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)

Client	Config file
Cursor (project)	.cursor/mcp.json
Cursor (global)	~/.cursor/mcp.json
Claude Desktop	claude_desktop_config.json
VS Code	.vscode/mcp.json

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