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

Ship from your AI assistant. The Easyship MCP server lets ChatGPT, Claude, Cursor, VS Code, Gemini, OpenAI agents and other MCP clients compare rates, create shipments, buy labels, book pickups, track parcels and read analytics, across 550+ couriers in 200+ countries.

Server URL

https://mcp.easyship.com/mcp

Transport

Streamable HTTP (remote) or stdio (local)

Auth

Easyship API token as a Bearer token

Tools

25 tools, API version 2024-09

What is MCP? The Model Context Protocol is an open standard for connecting AI assistants to tools. Your assistant discovers the Easyship tools, calls the right API endpoints for you, and keeps context across steps, so you can say "ship this to Toronto with the cheapest courier" instead of writing the API calls yourself.

On this page

Quick start
Supported platforms
Connect your client (ChatGPT, Claude, Cursor, VS Code, Gemini, Codex, OpenAI API)
Tools
Sample prompts
Authorization scopes
Troubleshooting
FAQ

Quick start

Step 1

Get an API token

Dashboard → Connect

→

Step 2

Add the server

mcp.easyship.com/mcp

→

Step 3

Ask in plain words

"Compare rates to Toronto"

Get your API token

Go to Easyship Dashboard → Connect and click New Integration.
Under API Integration, choose I am developing a custom integration.
Name it Easyship MCP, keep version 2024-09, enable the scopes you need, and click Connect.
Click Access Token and copy it.

Keep your token out of the chat. Put it in your client's config or an environment variable, never in a prompt. If it leaks, rotate it in the dashboard right away.

Supported platforms

Category	Platform	How to connect
AI coding tools	Cursor	Plugin Cursor Directory or config file
	VS Code	Config `.vscode/mcp.json`
	Windsurf	Config Manual MCP setup (remote URL)
Assistants	Claude Code	Plugin `/plugin install` or CLI
	Claude Desktop	Plugin Config file or plugin
	Grok	OAuth Setup guide
	ChatGPT	App Sign in with your Easyship account (OAuth). How to connect
Builders	OpenAI Responses API / Agents SDK	Bearer token in `headers`
	Gemini CLI	Extension `gemini extensions install`
	Codex CLI	Config `~/.codex/config.toml`
Automation	n8n, Activepieces, Zapier	MCP client Native MCP Client tool action (remote URL)
Skills	OpenClaw / Perplexity	Skill ClawHub skill

Connect your client

RECOMMENDED

Remote

Point your client at https://mcp.easyship.com/mcp with your token. Nothing to install.

LOCAL

Local (stdio)

Run easyship-mcp on your machine with uvx. Needs uv and Python 3.10+.

In every example, replace YOUR_TOKEN with your API token.

ChatGPT

Easyship is available as an app in ChatGPT. Add it from ChatGPT and sign in with your Easyship account; there's no API token to copy. Each action runs on your own account under the permissions you approve. Step-by-step: How to connect ChatGPT to the Easyship MCP server.

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global), then restart Cursor.

JSON.cursor/mcp.json

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

Claude Code

TerminalRemote (recommended)

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

TerminalLocal (uvx)

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

Claude CodePlugin

/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%\Claude\claude_desktop_config.json (Windows). Then quit and reopen Claude Desktop; closing the window isn't enough.

JSONclaude_desktop_config.json (local)

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

Claude Desktop uses the local method, so it needs uv and Python 3.10+.

VS Code

JSON.vscode/mcp.json

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

Gemini CLI

TerminalExtension

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

TerminalManual

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

Codex CLI

TOML~/.codex/config.toml

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

Then set export EASYSHIP_API_ACCESS_TOKEN="YOUR_TOKEN".

OpenAI Responses API / Agents SDK

For your own apps and agents, pass your API token in headers. More in the help center guide.

PythonResponses API

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)

Any other MCP client

Clients that support Streamable HTTP (Windsurf, n8n, Activepieces, Zapier and others):

SettingsRemote

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

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

Tools

Each tool calls one Easyship API endpoint.

Tool	What it does
Rates
`get_ratesPOST /rates`	Compare couriers by price, delivery time and duty estimate
Shipments
`create_shipmentPOST /shipments`	Create a shipment, optionally buying the label in the same call
`create_labelPOST /shipments/{id}/label`	Buy the label for an existing shipment
`get_shipmentGET /shipments/{id}`	Full details, including label, packing slip and invoice links
`list_shipmentsGET /shipments`	Find shipments by state, date, country and more
`update_shipmentPATCH /shipments/{id}`	Change address, parcel, courier or settings before the label is bought
`delete_shipmentDELETE /shipments/{id}`	Delete a shipment before a label is requested
`cancel_shipmentPOST /shipments/{id}/cancel`	Cancel after the label was requested, before it's in transit
`track_shipmentGET /shipments/trackings`	Status and checkpoints by shipment ID or order number
`get_shipment_documentsGET /shipments/{id}/documents`	Shipping documents, such as the commercial invoice
Pickups
`get_pickup_slotsGET /courier_services/{id}/pickup_slots`	Available pickup times for a courier
`create_pickupPOST /pickups`	Book a pickup for one or more shipments
`list_pickupsGET /pickups`	Find pickups by courier, date or state
`get_pickupGET /pickups/{id}`	Details of one pickup
`cancel_pickupPOST /pickups/{id}/cancel`	Cancel a booked pickup
`list_pickup_shipmentsGET /pickups/{id}/shipments`	Shipments in a pickup
Addresses
`validate_addressPOST /addresses/validations` (US: `/addresses/validations_domestic`)	Check and correct US and international addresses
Billing
`list_transactionsGET /transaction_records`	Transactions by type, date range or shipment
`list_billing_transactionsGET /billing_documents/{id}/transaction_records`	Transactions on one billing document
Analytics
`analytics_shipmentsGET /analytics/shipments`	Shipment volume with daily trend
`analytics_shippedGET /analytics/shipments_shipped`	Shipments with a label, for a date range
`analytics_shipment_statusGET /analytics/shipment_status`	Split by status: in transit, delivered, exception and so on
`analytics_destinations_by_volumeGET /analytics/top_shipments_destinations`	Top destinations by volume
`analytics_couriers_by_volumeGET /analytics/top_couriers`	Top couriers by shipment count
`analytics_sale_channelsGET /analytics/sale_channels`	Volume by sales channel (Shopify, WooCommerce, API...)

The older names analytics_top_couriers and analytics_top_destinations still work and map to the new ones.

Sample prompts

get_rates

Compare rates

"Ship a 2 kg parcel (30×20×15 cm) from New York 10001 to Toronto M5B 2H1. Category books_collectibles, value $8. Show the cheapest and fastest options."

validate_address

Validate an address

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

create_shipment

Draft a shipment

"Create a draft shipment, don't buy a label yet. From Acme LLC, 350 5th Ave, New York, NY 10001. To John Doe, 220 Yonge St, Toronto, ON M5B 2H1. 0.12 kg, 22×15×3 cm, one paperback book, $8. DDU."

create_shipment

Ship in one go

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

create_label

Label a draft

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

track_shipment

Track

"Track ESSG10006001. What's the latest status, the ETA and the last three events?"

get_pickup_slots → create_pickup

Book a pickup

"Book a pickup for ESSG10006001 and ESSG10006002. Find the courier's slots and take the earliest."

analytics_couriers_by_volume

Analytics

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

list_transactions

Billing

"Pull my shipment transactions from March 2026 and summarise the charges."

Authorization scopes

Enable these on your API token for the tools you'll use. See Scopes.

Scope	Tools
`public.rate:read`	`get_rates`
`public.shipment:read`	`get_shipment`, `list_shipments`, `list_pickup_shipments`
`public.shipment:write`	`create_shipment`, `update_shipment`, `delete_shipment`, `cancel_shipment`
`public.label:write`	`create_label`, and `create_shipment` / `update_shipment` when buying a label
`public.track:read`	`track_shipment`
`public.shipment_document:read`	`get_shipment_documents`
`public.pickup:read`	`get_pickup_slots`, `list_pickups`, `get_pickup`
`public.pickup:write`	`create_pickup`, `cancel_pickup`
`public.address_validation:write`	`validate_address` (non-US addresses)
`public.address_validation_domestic:write`	`validate_address` (US addresses)
`public.transaction_record:read`	`list_transactions`, `list_billing_transactions`
`public.analytics:read`	All `analytics_*` tools

A missing scope makes that tool fail with 403; the other tools keep working.

Troubleshooting

The server doesn't show up in my client.

Save the config and fully restart the client. Check the JSON is valid (no trailing commas).

Authentication errors, or only some tools work.

Re-copy the token from Dashboard → Connect → API with no extra spaces, and check it has the scopes for the tools you're using.

Remote mode won't connect.

Your client may not support Streamable HTTP. Use the local (uvx) method instead, and check you're using https://mcp.easyship.com/mcp.

uvx not found (local mode).

Install uv:

TerminalInstall uv

# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows (PowerShell) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Something else went wrong.

Report a bug with the tool name, error code and request ID from the error.

FAQ

Do I need to code?

No. If you can edit a config file and copy an API token, you can use it.

Can I use Easyship in ChatGPT?

Yes. Add the Easyship app in ChatGPT and sign in with your Easyship account. See ChatGPT above.

Can I create a shipment without buying the label?

Yes. Ask for a draft (or leave buy_label off). Buy the label later with create_label.

How do I book a pickup?

Ask the assistant: it gets the courier from get_shipment, finds times with get_pickup_slots, then books with create_pickup. All shipments in one pickup must use the same courier.

Can I use one token in several clients?

Yes. They share your account's rate limits, and avoid editing the same shipment from two clients at once.

Does the server store my data?

No. It's a stateless proxy to the Easyship API. Only request metadata (endpoint, status code, session ID) is logged for monitoring.

Built something with it? We'd love to hear how you use the Easyship MCP server. Share your feedback.