# mcp-ups

MCP server for UPS package tracking and shipping services. Uses Playwright browser automation to interact with the UPS website.

## Requirements

- Node.js 18 or higher
- Playwright (installed automatically as a dependency)

## Installation

```bash
npm install -g @striderlabs/mcp-ups
```

After installing, install the Playwright browser:

```bash
npx playwright install chromium
```

## Configuration for Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ups": {
      "command": "mcp-ups"
    }
  }
}
```

If using `npx` instead of a global install:

```json
{
  "mcpServers": {
    "ups": {
      "command": "npx",
      "args": ["-y", "@striderlabs/mcp-ups"]
    }
  }
}
```

## Tools

### `track_package`

Track a UPS package by tracking number. Returns current status, location history, and estimated delivery date.

**Parameters:**
- `tracking_number` (required): UPS tracking number (e.g., `1Z999AA10123456784`)

**Example:**
```json
{
  "tracking_number": "1Z999AA10123456784"
}
```

**Response:**
```json
{
  "tracking_number": "1Z999AA10123456784",
  "status": "In Transit",
  "estimated_delivery": "Thursday, March 14, 2026",
  "events": [
    {
      "date": "03/13/2026",
      "time": "8:00 A.M.",
      "location": "Louisville, KY, US",
      "status": "In Transit",
      "description": "Package transferred to destination facility"
    }
  ]
}
```

---

### `get_rates`

Get UPS shipping rates between two ZIP codes for a package of specified dimensions and weight.

**Parameters:**
- `from_zip` (required): Origin ZIP code
- `to_zip` (required): Destination ZIP code
- `weight_lbs` (required): Package weight in pounds
- `length_in` (optional): Package length in inches
- `width_in` (optional): Package width in inches
- `height_in` (optional): Package height in inches

**Example:**
```json
{
  "from_zip": "90210",
  "to_zip": "10001",
  "weight_lbs": 5,
  "length_in": 12,
  "width_in": 8,
  "height_in": 6
}
```

**Response:**
```json
{
  "from_zip": "90210",
  "to_zip": "10001",
  "weight_lbs": 5,
  "rates": [
    {
      "service_name": "UPS Ground",
      "price": "$12.34",
      "delivery_time": "1-5 business days",
      "guaranteed": false
    },
    {
      "service_name": "UPS Next Day Air",
      "price": "$45.67",
      "delivery_time": "Next business day",
      "guaranteed": true
    }
  ]
}
```

---

### `find_locations`

Find UPS Store locations, drop boxes, and access points near a given address or ZIP code.

**Parameters:**
- `address` (required): Address, city, or ZIP code to search near
- `radius_miles` (optional): Search radius in miles (default: 5)
- `location_type` (optional): Type of location — `store`, `dropbox`, `access_point`, or `all` (default: `all`)

**Example:**
```json
{
  "address": "90210",
  "radius_miles": 3,
  "location_type": "store"
}
```

**Response:**
```json
{
  "search_address": "90210",
  "locations": [
    {
      "name": "The UPS Store",
      "address": "123 Main St",
      "city": "Beverly Hills",
      "state": "CA",
      "zip": "90210",
      "phone": "(310) 555-1234",
      "hours": "Mon-Fri 8am-7pm, Sat 9am-5pm",
      "distance": "0.5 miles",
      "type": "UPS Location"
    }
  ]
}
```

---

### `schedule_pickup`

Schedule a UPS package pickup at your address. Note: This requires a UPS account login, so the tool will provide step-by-step instructions if authentication is needed.

**Parameters:**
- `address` (required): Pickup street address
- `city` (required): City
- `state` (required): State (2-letter code)
- `zip` (required): ZIP code
- `pickup_date` (required): Desired pickup date in `YYYY-MM-DD` format
- `num_packages` (optional): Number of packages (default: 1)
- `total_weight_lbs` (optional): Total weight in pounds (default: 5)

**Example:**
```json
{
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94105",
  "pickup_date": "2026-03-15",
  "num_packages": 2,
  "total_weight_lbs": 10
}
```

**Response:**
```json
{
  "success": false,
  "pickup_date": "2026-03-15",
  "address": "123 Main St, San Francisco, CA 94105",
  "message": "Scheduling a pickup requires a UPS account login",
  "instructions": "1. Visit https://www.ups.com/pickup/schedule\n2. Sign in to your UPS account\n..."
}
```

## Notes

- This server uses Playwright browser automation to interact with the UPS website. It does not use the UPS API directly.
- Some features (e.g., scheduling pickups) require a UPS account. The server will provide instructions for completing those steps manually.
- UPS website structure may change over time, which could affect data extraction accuracy.
- The server keeps a shared browser instance to reduce overhead across tool calls.

## License

MIT