MCP Server

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:
Copy
Copied
{
  "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:
Copy
Copied
{
  "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

Copy
Copied
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):

Copy
Copied
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:

Copy
Copied
npx @shippo/shippo-mcp --help

Usage Examples

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

Create a Shipping Label

Copy
Copied
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

Copy
Copied
Track package with tracking number: 1Z999AA10123456784

Validate an Address

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

Compare Shipping Rates

Copy
Copied
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

Copy
Copied
npx @shippo/shippo-mcp --version

Update to Latest Version

Copy
Copied
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.

Development

To build the MCP server from source:

  1. Clone the repository
  2. Install dependencies:
    Copy
    Copied
    npm install
  3. Build the server:
    Copy
    Copied
    npm run build
  4. The server binary will be at bin/mcp-server.js

Local Development Configuration

To run the server locally from source, use this configuration:

Copy
Copied
{
  "mcpServers": {
    "shippo-dev": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/REPO/bin/mcp-server.js",
        "start",
        "--api-key-header",
        "ShippoToken YOUR_SHIPPO_API_KEY",
        "--shippo-api-version",
        "2018-02-08"
      ]
    }
  }
}

Replace /ABSOLUTE/PATH/TO/REPO with the full path to your cloned repository.

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 Type Prefix Use Case
Test Keys shippo_test_ Development, testing, demos
Live Keys shippo_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:

Copy
Copied
# 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.