Skip to main content

​
Overview

The Shippo MCP (Model Context Protocol) Server enables AI assistants and LLMs to interact directly with the Shippo API through a standardized interface. This allows AI-powered applications to create shipments, generate labels, track packages, and manage shipping operations seamlessly.

​
What is MCP?

Model Context Protocol (MCP) is an open protocol developed by Anthropic that standardizes how AI applications communicate with external data sources and tools. The Shippo MCP Server implements this protocol, making Shippo’s shipping capabilities accessible to AI assistants like Claude, Cursor, and other MCP-compatible clients.

​
Features

The Shippo MCP Server provides access to core Shippo API functionality:

​
Address Management

  • Validate Addresses: Verify and standardize shipping addresses
  • Create Address Records: Store addresses for future use
  • Address Book: Manage sender and recipient addresses

​
Shipping Operations

  • 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

​
Carrier Accounts

  • 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

​
International Shipping

  • Customs Declarations: Create customs documentation for international shipments
  • Customs Items: Define items for customs processing
  • Multi-Country Support: Ship internationally with proper documentation

​
Advanced Features

  • Batch Operations: Process multiple shipments at once
  • Pickups: Schedule carrier pickups
  • Manifests: Generate end-of-day manifests
  • Webhooks: Set up event notifications

​
Getting Started

​
Prerequisites

  • Node.js v18+
  • A Shippo account (sign up here — it’s free!)
  • Your Shippo API token
  • An MCP-compatible client (Cursor, Claude Desktop, or other MCP clients)

​
Get Your API Key

  1. Sign up or log in at goshippo.com
  2. Navigate to API Settings
  3. Generate a new API key
  4. Copy the key for use in your MCP configuration
Tip: Use test API keys (starting with shippo_test_) during development. Test labels are free — you only pay when printing live labels. Important: When configuring the server, you must include the ShippoToken prefix before your key (e.g., ShippoToken shippo_test_...).

​
Installation

Choose your preferred MCP client below:

​
Cursor

The easiest way to install is using the one-click installer: Install MCP Server
⚠️ Important: Click Install first to add the server. Then, go to Settings → Tools & MCP → shippo-mcp (edit) to edit the configuration. Replace YOUR_SHIPPO_API_KEY with your actual API key (ensure you keep or add the ShippoToken prefix), then save mcp.json. You may need to toggle the server off and on for changes to take effect.

​
Manual Cursor Installation

  1. Open Cursor Settings
  2. Select Tools and Integrations
  3. Click New MCP Server
  4. Paste the following configuration:
{
  "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"
      ]
    }
  }
}
  1. Replace YOUR_SHIPPO_API_KEY with your actual API key (keeping the ShippoToken prefix)
  2. Save and restart Cursor

​
Claude Desktop

  1. Open Claude Desktop
  2. Click on your Username in the left sidebar
  3. Go to Settings
  4. Select the Developer tab
  5. Click Edit Config
  6. Add the Shippo MCP Server configuration:
{
  "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"
      ]
    }
  }
}
  1. Replace YOUR_SHIPPO_API_KEY with your actual API key (keeping the ShippoToken prefix)
  2. Save and restart Claude Desktop

​
Claude Code CLI

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 MCP server directly (useful for debugging or manual connections): 
npx -y @shippo/shippo-mcp start --api-key-header "ShippoToken YOUR_SHIPPO_API_KEY" --shippo-api-version 2018-02-08
Note: This starts the server in stdio mode, waiting for MCP protocol messages. It won’t show an interactive prompt — it’s designed to be connected to by an MCP client like Cursor or Claude Desktop.
For a full list of server arguments: 
npx @shippo/shippo-mcp --help

​
Usage Examples

Once configured, 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

​
Updating

The MCP server is distributed via npm. To ensure you have the latest features and bug fixes, update periodically.

​
Check Current Version

npx @shippo/shippo-mcp --version

​
Update to Latest Version

npm update -g @shippo/shippo-mcp
Next time you start your MCP client (Cursor, Claude), it will fetch the latest version.
Tip: After updating, toggle your MCP server off and on in Cursor/Claude settings for changes to take effect.

​
Testing

The Shippo MCP Server supports Shippo’s test mode. When using test API tokens (those starting with shippo_test_), all operations will use test mode and won’t create real shipments or charges. Test mode benefits:
  • Free test labels
  • No charges to your account
  • Safe experimentation
  • Full API functionality

​
Security

​
API Key Management

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 for security
  • Never share keys publicly
  • Store keys in environment variables or secure credential stores

​
Environment Variables

For added security, you can store your API key in an environment variable: 
# Add to ~/.zshrc or ~/.bashrc
export SHIPPO_API_KEY="your_api_key_here"
Then reference it in your configuration as needed.

​
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.