Easyship Shipping MCP Server: Connect AI Agents To Shipping APIs Across 550+ Courier & Postage Services

Integrate shipping operations directly into AI-powered workflows using natural language. Compare rates, create shipments, buy labels, schedule pickups, track deliveries, and analyze data — across 550+ couriers in 200+ countries.

The Easyship Model Context Protocol (MCP) server provides tools that AI agents can use to interact with the Easyship API. Instead of manually orchestrating API calls, developers connect an MCP-compatible client and let the AI assistant handle end-to-end logistics tasks.

What is MCP? Model Context Protocol is an open standard that allows AI clients to connect to external tools and services. The AI assistant discovers available tools, executes structured operations, and maintains context across workflows. Learn more →

Supported platforms

AI coding environments

Platform	How to connect
Cursor	Plugin Cursor Marketplace or manual config
VS Code	MCP config `.vscode/mcp.json`
Windsurf	MCP config Manual MCP setup

Chat & assistant apps

Platform	How to connect
Claude Desktop	Plugin Config file or AI Toolkit
Claude Code	Plugin `/plugin install` or CLI command
ChatGPT	Coming soon

Cloud AI & APIs (for builders)

Platform	How to connect
OpenAI Responses API / Agents SDK	Pass Bearer token in `headers`
Gemini CLI	Extension `gemini extensions install`
Codex CLI	MCP config `~/.codex/config.toml`

Workflow automation

Platform	How to connect
n8n	MCP client Native MCP Client Tool Action
Activepieces	MCP client Native MCP Client Tool Action
Zapier	MCP client Native MCP Client Tool Action

Skills-first / hybrid

Platform	How to connect
OpenClaw / Perplexity	Skill ClawHub skill

Setup guide

Prerequisites

Before connecting, you need:

Easyship account	Sign up free
API token	With required scopes — see Authorization scopes
MCP-compatible client	See Supported platforms above
Python 3.8+ (local mode only)	With uv installed. Not needed for remote.

Get your API token

Go to Easyship Dashboard → Connect and click New Integration

Scroll to API Integration

Select "I am developing a custom integration"

Name the key Easyship MCP for easy reference

Keep the default version 2024-09 and click Connect

Click Access Token and copy it using the copy button

Tip: The remote server at mcp.easyship.com is always available — no installation or local setup required. Just point your MCP client to the URL with your token.

Connect to the MCP server

Two connection methods are available:

Remote	Connects to `mcp.easyship.com` — no dependencies needed
Local	Runs `easyship-mcp` on your machine via `uvx` — requires uv + Python 3.8+

⚠️ Security Note: Never share your API token in the chat window. If you accidentally paste it in a prompt, revoke and rotate your API key immediately in the Easyship Dashboard.

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

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

Replace YOUR_TOKEN with your API token. Save and restart Cursor.

Claude Code

Remote (recommended)

claude mcp add --transport http easyship   https://mcp.easyship.com/mcp   --header 'Authorization:Bearer YOUR_TOKEN'

Local (uvx)

export EASYSHIP_API_ACCESS_TOKEN="YOUR_TOKEN"
claude mcp add easyship -- uvx easyship-mcp

Via plugin

/plugin marketplace add easyship/easyship-ai-toolkit
/plugin install easyship-plugin@easyship-ai-toolkit

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%Claudeclaude_desktop_config.json (Windows):

{
  "mcpServers": {
    "easyship": {
      "command": "uvx",
      "args": ["easyship-mcp"],
      "env": {
        "EASYSHIP_API_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Replace YOUR_TOKEN. Save and fully restart Claude Desktop (quit, don't just close the window).

Note: Claude Desktop uses the local (uvx) method, which requires uv and Python 3.8+ installed on your machine.

VS Code

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "easyship": {
      "type": "http",
      "url": "https://mcp.easyship.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Gemini CLI

gemini extensions install https://github.com/easyship/easyship-ai-toolkit

Or add manually:

gemini mcp add --transport http easyship   https://mcp.easyship.com/mcp   --header 'Authorization:Bearer YOUR_TOKEN'

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.easyship]
url = "https://mcp.easyship.com/mcp"
bearer_token_env_var = "EASYSHIP_API_ACCESS_TOKEN"

Then set the environment variable: export EASYSHIP_API_ACCESS_TOKEN="YOUR_TOKEN"

OpenAI API

Use the Easyship MCP server with OpenAI's Responses API:

# Python
from openai import OpenAI

client = OpenAI()
resp = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "easyship",
        "server_url": "https://mcp.easyship.com/mcp",
        "require_approval": "never",
        "headers": {
            "Authorization": "Bearer YOUR_EASYSHIP_TOKEN"
        }
    }],
    input="What are the cheapest shipping options from HK to NYC for a 1.5kg package?"
)
print(resp.output_text)

Note: This works with the Responses API and Agents SDK today. For ChatGPT consumer UI (chat.openai.com), OAuth support is required — coming soon.

Other Clients

For any MCP client that supports Streamable HTTP:

URL:    https://mcp.easyship.com/mcp
Header: Authorization: Bearer YOUR_TOKEN

For stdio-based clients, run uvx easyship-mcp with EASYSHIP_API_ACCESS_TOKEN set in the environment.

Tools

The server exposes the following MCP tools. Each tool maps to one or more Easyship API endpoints.

Resource	Tool	Description
Rates	get_rates	Compare courier options with prices, delivery times, and duty estimates

Shipments	create_shipment	Create a shipment and optionally buy a label in one call
	create_label	Buy a shipping label for an existing shipment by shipment ID
	get_shipment	Get full details including label, packing slip, and invoice URLs
	list_shipments	List and filter shipments by state, date, country, and more
	update_shipment	Update address, parcel, courier, or shipping settings
	delete_shipment	Delete a shipment that hasn't shipped yet
	cancel_shipment	Cancel a shipped shipment (pre-transit only)
	track_shipment	Track by shipment ID or order number with checkpoint history
	get_shipment_documents	Retrieve commercial invoice metadata

Pickups	get_pickup_slots	Get available pickup time slots for a courier
	create_pickup	Schedule a pickup for one or more shipments
	list_pickups	List pickups with filters (courier, date, state)
	get_pickup	Get details of a specific pickup
	cancel_pickup	Cancel a scheduled pickup
	list_pickup_shipments	List all shipments in a pickup

Address	validate_address	Validate US domestic and international addresses

Billing	list_transactions	List transactions by type, date range, or shipment
Billing	list_billing_transactions	List transactions for a billing document

Analytics	analytics_shipments	Shipment volume overview with daily trends
	analytics_shipped	Shipped (label-generated) shipment data for a date range
	analytics_shipment_status	Status distribution — in-transit, delivered, exception, etc.
	analytics_top_destinations	Top destinations ranked by volume
	analytics_top_couriers	Top couriers ranked by shipment count
	analytics_sale_channels	Volume by sales channel (Shopify, WooCommerce, API, etc.)

Sample prompts

Once connected, interact with Easyship using natural language. Here are examples for each tool category:

Compare rates get_rates

"I want to ship a 2 kg parcel (30×20×15 cm) from New York, US 10001 to Toronto, Canada M5B 2H1. Category is books_collectibles, declared value $8 USD. Show cheapest and fastest options."

Validate address validate_address

"Is this address valid for shipping: 1600 Amphitheatre Parkway, Mountain View, CA 94043, US? Show any suggested corrections."

Create draft shipment create_shipment

"Create a draft shipment (don't buy a label yet). From: Acme LLC, Jane Sender, [email protected], +1 212-555-0147, 350 5th Ave, New York, NY 10001, US. To: John Doe, [email protected], +1 416-555-0199, 220 Yonge St, Toronto, ON M5B 2H1, CA. Package: 0.12 kg, 22×15×3 cm. Item: paperback book, 1 unit, $8 USD, category books_collectibles. DDU."

Buy a label create_shipment

"Ship a 2 kg parcel from SF to NYC with the cheapest courier. Buy the label and give me the download link."

Label an existing shipment create_label

"Buy a label for shipment ESSG10006001 and give me the download link."

Track a shipment track_shipment

"Track shipment ESSG10006001 — what's the latest status, ETA, and last three tracking events?"

Get shipment details get_shipment

"Pull up shipment ESSG10006001. I need the full details with document links as URLs — 4×6 label and packing slip, A4 commercial invoice."

Schedule a pickup get_pickup_slots → create_pickup

"Schedule a pickup for shipments ESSG10006001 and ESSG10006002. Get the courier ID from the first shipment, find available slots, and book the earliest one."

Analytics analytics_top_couriers

"For the last 3 months, which couriers did I use the most? Rank them with counts and share of volume."

Transaction history list_transactions

"Pull my transactions from March 2026, type shipment, 50 per page. Give me a summary of charges."

Authorization scopes

Each tool requires specific API token scopes. When creating your token, enable the scopes needed for the tools you plan to use. See API Scopes for full details.

Scope	Used by
public.shipment:read	list_shipments, get_shipment, track_shipment, list_pickup_shipments
public.shipment:write	create_shipment, update_shipment, delete_shipment, cancel_shipment
public.label:write	create_shipment (when buying a label), create_label
public.pickup:read	get_pickup_slots, list_pickups
public.pickup:write	create_pickup, get_pickup, cancel_pickup
public.shipment_document:read	get_shipment_documents
public.transaction_record:read	list_transactions, list_billing_transactions
public.analytics:read	All analytics_* tools
public.address_validation:write	validate_address (international)
public.address_validation_domestic:write	validate_address (US)

Troubleshooting

Server Visibility Issues

Save the config file and fully restart the client app. For Claude Desktop, quit and reopen — closing the window isn't enough.

Resolving Authentication Errors

Re-check your token at Dashboard → Connect → API. Ensure there are no extra spaces or line breaks. Verify the token has the required scopes for the tools you're using.

Incomplete Tool Loading

Verify your API token is valid and active. Restart your MCP client/session. If the issue persists, check your network connection and ensure you're connecting to https://mcp.easyship.com/mcp.

Missing Dependencies `uvx` not found? (local mode only)

Install uv first:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Remote mode not connecting?

Verify your client supports Streamable HTTP transport. If not, use the local (uvx) method.

Security: Never commit API tokens to version control. Use environment variables or a secrets manager. Rotate tokens periodically from the dashboard.

FAQ

Do I need coding experience to use the Easyship MCP Server?

Basic technical familiarity helps, but deep coding experience isn't required. If you can install tools, manage API keys, and follow setup instructions, you can use the MCP server.

Is there a native Easyship plugin for ChatGPT?

Not yet. ChatGPT Apps require OAuth support on the MCP server, which is on our roadmap. In the meantime, developers can use the Easyship MCP server via OpenAI's Responses API by passing the Easyship API token as a Bearer token — no OAuth needed for API access.

Can I create a shipment without immediately buying a label?

Yes. Omit buy_label or set it to false in the shipment data. The shipment is created in draft state and you can buy the label later with create_label when ready.

How do I schedule or cancel a courier pickup?

To schedule: use get_shipment to get the courier service ID, then get_pickup_slots to see available times, then create_pickup with your chosen slot. All shipments in a pickup must use the same courier. To cancel: use cancel_pickup with the pickup ID.

Can I use the same API token across multiple MCP clients?

Yes. Be mindful of rate limits and avoid conflicting operations (e.g., modifying the same shipment from two clients simultaneously).

What should I do if not all tools load after connecting?

Verify your API token is valid and has all required scopes. Restart your MCP client. Check your network connection. If using the local method, ensure you have the latest version: pip install --upgrade easyship-mcp.

API version: v2024-09 · Package: easyship-mcp on PyPI · MCP Registry · AI Toolkit on GitHub

Supported platforms

AI coding environments

Chat & assistant apps

Cloud AI & APIs (for builders)

Workflow automation

Skills-first / hybrid

Setup guide

Prerequisites

Get your API token

Connect to the MCP server

Cursor

Claude Code

Remote (recommended)

Local (uvx)

Via plugin

Claude Desktop

VS Code

Gemini CLI

Codex CLI

OpenAI API

Other Clients

Tools

Sample prompts

Authorization scopes

Troubleshooting

Server Visibility Issues

Resolving Authentication Errors

Incomplete Tool Loading

Missing Dependencies uvx not found? (local mode only)

Remote mode not connecting?

FAQ

Missing Dependencies `uvx` not found? (local mode only)