Easyship - Shipping MCP

Safety rules for Easyship shipping operations — confirms destructive actions, protects secrets, and validates inputs before API calls

# Easyship Safety Rules

## Destructive actions require confirmation

Before calling `delete_shipment`, `cancel_shipment`, or `cancel_pickup`, always ask the user to confirm. Show the shipment/pickup ID and current status so they can make an informed decision.

## Never expose API tokens

Never display, log, or include `EASYSHIP_API_ACCESS_TOKEN` in responses, code snippets, or file contents. If the user shares a token in chat, warn them and suggest rotating it.

## Validate required fields before API calls

Before calling `create_shipment`, verify that all required address fields are present: contact name, email, phone, street, city, and country code for both origin and destination. If any are missing, ask the user rather than guessing.

Before calling `get_rates`, ensure origin country, destination country, weight, and all three dimensions (length, width, height) are provided. Prompt for missing values.

## Handle errors gracefully

If an API call returns an error, present the error message clearly and suggest a fix. Common issues:
- 401 Unauthorized → token is missing or expired, direct to https://app.easyship.com/connect/api
- 422 Unprocessable → missing or invalid fields, show which fields need correction
- 429 Rate limited → wait and retry, inform the user

## Currency and units

Always include the currency code when displaying prices. Do not convert currencies unless the user asks. Weights are in kg and dimensions in cm unless the user specifies otherwise.

MCP server: easyship

{
  "mcpServers": {
    "easyship": {
      "url": "https://mcp.easyship.com/mcp",
      "headers": {
        "Authorization": "Bearer ${EASYSHIP_API_ACCESS_TOKEN}"
      }
    }
  }
}

Easyship Shipping MCP to compare rates, create shipments, buy labels, track packages, and schedule pickups from your agent across 550+ couriers in 200+ countries. Hosted server, no local setup.

> Remote MCP **v0.4.0** — 25 tools across shipping, tracking, pickups, billing, address validation, and analytics. Server implementation: [easyship/easyship-mcp](https://github.com/easyship/easyship-mcp).

## Shipping rates

### get_rates

Use when the user asks about shipping costs, delivery times, courier options, or the cheapest/fastest way to ship.

**Required inputs:** origin country, destination country, parcel weight, dimensions (length/width/height).

**Optional (improves accuracy):** city, state, postal code, street address for origin and destination. Item category or HS code for duty estimates.

**Presenting results:**
- Show a comparison table: courier name, price, currency, estimated delivery days.
- Sort by price (lowest first) unless the user asks for fastest.
- If you used assumed/estimated data (e.g. generic postal codes), tell the user the rates are estimates.

## Shipments

### create_shipment

The primary tool for creating shipments and buying labels.

**For "ship this" / "buy a label":** set `buy_label: true` and `buy_label_synchronous: true` with `format: "url"` in printing options. Extract the label URL from `shipping_documents` in the response and present it as a clickable link.

**For a specific courier** (e.g. "buy a label with UPS Ground"): call `get_rates` first to find the `courier_id`, then pass it in `courier_settings`.

**Without a specific courier:** omit `courier_service_id` — the API auto-selects best value. Do NOT call `get_rates` first.

**Required inputs:** complete origin and destination addresses (contact name, email, phone, street, city, country code, and company name for origin), parcel weight, item description and customs value.

### update_shipment / get_shipment / list_shipments / delete_shipment / cancel_shipment

- `get_shipment` — retrieves full shipment details. Also use this to get label/document download URLs (pass `format="URL"`).
- `list_shipments` — filter by state, date range, country, etc. Supports label_state, delivery_state, shipment_state filters.
- `delete_shipment` — removes a shipment that hasn't shipped yet.
- `cancel_shipment` — cancels a shipped shipment (only if label failed or shipment not yet in transit).

### get_shipment_documents

Returns metadata only (content type, size). For actual document downloads, use `get_shipment` with `format="URL"` instead.

## Tracking

### track_shipment

Use when the user asks to track a package, check delivery status, or says "where's my shipment."

**Required input:** either `easyship_shipment_id` or `platform_order_number` — at least one must be provided.

**Presenting results:**
- Current status, last known location, estimated delivery date.
- List recent tracking checkpoints.

## Pickups

### get_pickup_slots → create_pickup

**Workflow for scheduling a pickup:**
1. Get the `courier_service_id` from the shipment via `get_shipment`
2. Call `get_pickup_slots` to find available dates and time windows
3. Present options to the user (or pick the earliest if they want the closest)
4. Call `create_pickup` with the chosen slot, date, and shipment IDs

All shipments in a pickup must use the same courier and have labels pending or generated.

### list_pickups / get_pickup / cancel_pickup / list_pickup_shipments

Standard CRUD for managing existing pickups.

## Address validation

### validate_address

Validates both US domestic and international addresses in a single tool. Omit `country_alpha2` or pass "US" for domestic; any other country code routes to international validation.

> Requires the Address Validation feature to be enabled on your Easyship account.

## Billing

### list_transactions / list_billing_transactions

View transaction history filtered by type (shipment, pickup, claim, policy, payment), date range, or shipment ID.

## Analytics

Six analytics tools, all defaulting to a 90-day lookback if the user doesn't specify a date range:

| Tool | Use for | Returns |
|------|---------|---------|
| `analytics_shipments` | Shipment volume and trends | Total count + daily time series |
| `analytics_shipped` | Past shipping activity confirmation | Whether account has ever shipped |
| `analytics_shipment_status` | Status distribution | Counts by status (in-progress breakdown) |
| `analytics_top_destinations` | Where shipments go | Countries/zones ranked by volume |
| `analytics_top_couriers` | Courier usage breakdown | Couriers ranked by shipment count |
| `analytics_sale_channels` | Sales channel breakdown | Channels ranked by shipment count |

## General

- Easyship supports 550+ couriers across 200+ countries/territories.
- An API token is required. If not configured, direct the user to: https://app.easyship.com/connect
- All prices are returned in the user's Easyship account currency unless specified otherwise.
- Always confirm destructive actions (delete/cancel) with the user before executing.