Skip to main content

​
Overview

The Shippo MCP (Model Context Protocol) Server lets AI assistants and LLMs interact with the Shippo API in natural language: compare carrier rates, buy shipping labels, track packages, validate addresses, handle customs for international shipments, and process batches. There are two ways to connect:
  • Hosted server (recommended): connect your MCP client to Shippo’s remote server at https://mcp.shippo.com and authorize with your Shippo account. Nothing to install, no API key to manage.
  • Local server (npm package): run the @shippo/shippo-mcp package on your own machine and authenticate with a Shippo API key. Good for local development, self-hosting, or clients that connect to a local stdio server.
Both expose the same Shippo capabilities. Pick whichever fits your client and workflow.

​
What is MCP?

Model Context Protocol (MCP) is an open protocol, developed by Anthropic, that standardizes how AI applications connect to external tools and data. The Shippo MCP Server implements it, making Shippo’s shipping capabilities available to MCP-compatible clients such as Claude, ChatGPT, and Cursor.

​
Features

The Shippo MCP Server provides access to core Shippo API functionality:
  • Validate addresses: verify and standardize shipping addresses
  • Create address records: store addresses for future use
  • Address book: manage sender and recipient addresses
  • Create shipments: set up shipments with origin, destination, and parcel details
  • Get rates: compare shipping rates across multiple carriers
  • Generate labels: purchase shipping labels for your shipments
  • Track packages: monitor shipment status and location
  • List carrier accounts: view all connected carrier accounts
  • Manage carriers: add or update carrier account settings
  • Multi-carrier support: works with USPS, UPS, FedEx, DHL, and more
  • Customs declarations: create customs documentation for international shipments
  • Customs items: define items for customs processing
  • Multi-country support: ship internationally with proper documentation
  • Batch operations: process multiple shipments at once
  • Pickups: schedule carrier pickups
  • Manifests: generate end-of-day manifests
  • Webhooks: set up event notifications
Connect any MCP-compatible client to https://mcp.shippo.com. The first time you use it, your client opens a Shippo sign-in window. Authorize it once and you are connected.
SettingValue
Server URLhttps://mcp.shippo.com
TransportRemote MCP over streamable HTTPS
AuthenticationSign in to Shippo (OAuth)
There is no API key to configure for the hosted server: authentication is handled by signing in to your Shippo account. The hosted server operates against your live Shippo account. To work in test mode (test labels, no charges), run the local server with a test key instead, see Local server below.
Quick add (one click). If your client supports it, add Shippo in one click; you will still complete the Shippo sign-in on first use. Otherwise, follow the per-client steps below.

Cursor

VS Code

LM Studio

Goose

Claude and ChatGPT don’t offer a one-click add; use their steps below.

​
Claude (claude.ai and Claude Desktop)

  1. Open Customize and go to Connectors.
  2. Click +, then Add custom connector.
  3. Name it Shippo and paste the server URL https://mcp.shippo.com. Leave the advanced OAuth fields blank.
  4. Click Add, then complete the Shippo sign-in when prompted.
Team and Enterprise admins can make Shippo available to everyone: in Organization settings → Connectors, choose Add → Custom → Web, enter the URL, and add it. Members then connect it under Customize → Connectors and complete the Shippo sign-in individually on first use.

​
Claude Code

claude mcp add --transport http shippo https://mcp.shippo.com
Then run /mcp, select the Shippo server, and complete the browser sign-in to authorize.

​
ChatGPT

  1. In Settings, open Apps & Connectors and, under Advanced settings, enable Developer mode (available on plans that support custom connectors).
  2. Choose Create, name it Shippo, and paste the connector URL https://mcp.shippo.com.
  3. Create the connector; ChatGPT opens the Shippo authorization window. Complete the sign-in.

​
Cursor

Add a remote MCP server in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global): 
{
  "mcpServers": {
    "shippo": {
      "url": "https://mcp.shippo.com"
    }
  }
}
Cursor supports OAuth for remote MCP servers. After saving the config, open Settings → Tools & Integrations, find Shippo, and complete the sign-in prompt.

​
Other MCP clients

Any client that supports a remote MCP server over HTTP with OAuth can connect: use the URL https://mcp.shippo.com and complete the Shippo authorization when prompted.

​
Local server (npm package)

Prefer to run the server yourself? The @shippo/shippo-mcp package runs locally over stdio and authenticates with a Shippo API key.

​
Prerequisites

  • Node.js v18+
  • A Shippo account (sign up here, it’s free) and your Shippo API token
  • An MCP-compatible client that connects to a local server (Cursor, Claude Desktop, Claude Code, and others)

​
Get your API key

  1. Sign up or log in at goshippo.com
  2. Navigate to API Settings
  3. Generate a new API key
Use test API keys (starting with shippo_test_) during development. Test labels let you build and experiment; you only pay when printing live labels.Important: when configuring the local server, include the ShippoToken prefix before your key (for example, ShippoToken shippo_test_...).

​
Cursor

The easiest way to install is the one-click installer: Install MCP Server After installing, go to Settings → Tools & Integrations → shippo-mcp (edit) and replace YOUR_SHIPPO_API_KEY with your actual key (keep the ShippoToken prefix), then save. Toggle the server off and on for changes to take effect. Or add it manually in .cursor/mcp.json: 
{
  "mcpServers": {
    "shippo-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@shippo/shippo-mcp",
        "start",
        "--api-key-header",
        "ShippoToken YOUR_SHIPPO_API_KEY",
        "--shippo-api-version",
        "2018-02-08"
      ]
    }
  }
}

​
Claude Desktop

In Claude Desktop, go to Settings → Developer → Edit Config and add: 
{
  "mcpServers": {
    "shippo-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@shippo/shippo-mcp",
        "start",
        "--api-key-header",
        "ShippoToken YOUR_SHIPPO_API_KEY",
        "--shippo-api-version",
        "2018-02-08"
      ]
    }
  }
}
Replace YOUR_SHIPPO_API_KEY with your key (keeping the ShippoToken prefix), then save and restart Claude Desktop.

​
Claude Code

claude mcp add shippo-mcp -- npx -y @shippo/shippo-mcp start --api-key-header "ShippoToken YOUR_SHIPPO_API_KEY" --shippo-api-version 2018-02-08

​
Command line

Run the server directly (useful for debugging): 
npx -y @shippo/shippo-mcp start --api-key-header "ShippoToken YOUR_SHIPPO_API_KEY" --shippo-api-version 2018-02-08
This starts the server in stdio mode, waiting for MCP protocol messages; it is designed to be connected to by an MCP client. For all server arguments, run npx @shippo/shippo-mcp --help.

​
Updating

The local server is distributed via npm. Check your version with npx @shippo/shippo-mcp --version, and update with: 
npm update -g @shippo/shippo-mcp
Toggle your MCP server off and on in your client for changes to take effect.

​
Usage examples

Once connected, you can interact with Shippo through natural language:

​
Create a shipping label

Create a shipping label from:
123 Main St, San Francisco, CA 94105

To:
456 Market St, New York, NY 10001

Package dimensions: 10x8x6 inches, 2 lbs

​
Track a package

Track package with tracking number: 1Z999AA10123456784

​
Validate an address

Validate this address:
215 Clayton St, San Francisco, CA 94117

​
Compare shipping rates

Get shipping rates for a 5lb package (12x10x8 inches)
from Los Angeles, CA 90001 to Chicago, IL 60601
Actions that buy a label or otherwise change your account ask for confirmation before they run.

​
Test vs live mode

Shippo’s test mode gives you test labels and mock tracking with no charges, so you can build and experiment safely. Test mode is key-based, so it is available on the local server only.
  • Local server: the mode follows the API key you configure. Use a test key (shippo_test_) for test mode, or a live key (shippo_live_) for production.
  • Hosted server: OAuth authorizes your live Shippo account, so the hosted server has no test mode. Read operations (rate comparison, address validation, tracking) do not incur charges, but purchasing a label is a live action that charges your account, write actions ask for confirmation first. To experiment without charges, use the local server with a test key.
Test mode benefits (local server with a test key):
  • Test labels
  • No charges to your account
  • Safe experimentation
  • Full API functionality
Test and live data (and object IDs) are completely separate.

​
Security

​
Hosted server

Requests are sent to Shippo’s hosted MCP server over HTTPS, authenticated by your per-user Shippo authorization, and forwarded to the Shippo API on your behalf. There is no API key to store and no local process in the path. To disconnect, remove the Shippo connector from your client’s settings and revoke access from your Shippo account if desired.

​
Local server (API key)

Key TypePrefixUse Case
Test Keysshippo_test_Development, testing, demos
Live Keysshippo_live_Production only
Best practices:
  • Never commit API keys to source control
  • Use test keys during development
  • Rotate keys regularly
  • Never share keys publicly
  • Store keys in environment variables or a secure credential store

​
Troubleshooting

  • Shippo doesn’t appear in the connector or tool picker: confirm the server was added and (hosted) the Shippo sign-in completed. Reopen your client’s connector settings to check its status.
  • Hosted: you’re asked to sign in again: the authorization session expired. Re-authorize from the connector settings (in Claude Code, run /mcp).
  • Hosted: the sign-in window is blocked: allow pop-ups for your client and retry.
  • Local: authentication errors: verify the ShippoToken prefix is present on your key and that the key matches the mode you intend (test vs live).
  • Local: tools missing after an update: toggle the server off and on in your client so it picks up the new version.

​
Resources

​
Support

For questions or issues:

​
About Shippo

Connect with multiple carriers, get discounted shipping labels, track parcels, and much more with just one integration. You can use your own carrier accounts or take advantage of Shippo’s discounted rates. Shippo simplifies carrier integrations, rate shopping, tracking, and the entire shipping workflow.