Shippo MCP Server

Model Context Protocol (MCP) Server for the Shippo API.

You must register for a Shippo account to use our API. It's free to sign up. Only pay to print a live label — test labels are free.
To use the MCP server, you'll need an API Token. Replace YOUR_SHIPPO_API_KEY with your own token (including the ShippoToken prefix) in the examples below.

Summary

Shippo MCP Server: Use this MCP Server to integrate with the Shippo service using natural language and agentic flows.

Requirements

• Node.js 18+ — Download Node.js

Table of Contents

• Shippo MCP Server
  • Requirements
  • Quick Start
  • Configuration
  • Updating
  • Troubleshooting
  • Features
  • Security
  • Contributions
  • Support
  • About Shippo

Quick Start

⚠️ 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 (keep the ShippoToken prefix), then save mcp.json, and toggle shippo-mcp on and off for changes to take effect.

Or manually:

1. Open Cursor Settings
2. Select Tools and Integrations
3. Select New MCP Server
4. If the configuration file is empty paste the following JSON into the MCP Server Configuration:

{
  "mcpServers": {
    "shippo-mcp": {
      "command": "npx",
      "args": [
        "@shippo/shippo-mcp",
        "start",
        "--api-key-header",
        "ShippoToken YOUR_SHIPPO_API_KEY",
        "--shippo-api-version",
        "2018-02-08"
      ]
    }
  }
}

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

You need to do the following

1. Open claude Desktop
2. Open left hand side pane, then click on your Username
3. Go to Settings
4. Go to Developer tab (on the left hand side)
5. Click on Edit Config Paste the following config in the configuration

{
  "mcpServers": {
    "shippo-mcp": {
      "command": "npx",
      "args": [
        "@shippo/shippo-mcp",
        "start",
        "--api-key-header",
        "ShippoToken YOUR_SHIPPO_API_KEY",
        "--shippo-api-version",
        "2018-02-08"
      ]
    }
  }
}

If you need to start the MCP server manually (e.g., for use with other MCP clients or debugging), run:

npx @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, run:

npx @shippo/shippo-mcp --help

Configuration

Cursor / Claude

{
  "mcpServers": {
    "shippo-mcp": {
      "command": "npx",
      "args": [
        "@shippo/shippo-mcp",
        "start",
        "--api-key-header",
        "ShippoToken YOUR_SHIPPO_API_KEY",
        "--shippo-api-version",
        "2018-02-08"
      ]
    }
  }
}

Command Line

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

To build the server from source:

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

Local Configuration

To run the server locally from source (e.g., for development), use the following configuration in Cursor or Claude:

{
  "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.

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.

Troubleshooting

ReferenceError: Response is not defined

This error occurs when running with Node.js < 18, or when the npx cache contains a stale installation from an older Node version.

If you use nvm (Node Version Manager):

# 1. Set Node 18+ as default
nvm alias default 20
nvm use 20

# 2. Verify Node version
node --version   # Should show v20.x.x or v18.x.x

# 3. Clear npm/npx caches (this is the key step)
npm cache clean --force
rm -rf ~/.npm/_npx/

# 4. (Optional) Clear nvm's cache too
nvm cache clear

# 5. Restart terminal to pick up fresh environment
exec "$SHELL"

# 6. Verify npx will use correct Node
which npx   # Should point to v20 or v18 path

Then restart your MCP client (Cursor/Claude Desktop).

Alternative: Global Install

If cache issues persist, install globally instead of using npx:

npm install -g @shippo/shippo-mcp

Then update your MCP configuration to use the global command directly:

{
  "mcpServers": {
    "shippo-mcp": {
      "command": "shippo-mcp",
      "args": [
        "start",
        "--api-key-header",
        "ShippoToken YOUR_SHIPPO_API_KEY",
        "--shippo-api-version",
        "2018-02-08"
      ]
    }
  }
}

Features

Address Management

• Create and validate addresses
• List existing addresses
• Retrieve address details

Shipment Management

• Create shipments with from/to addresses and parcels
• List shipments with filtering options
• Retrieve shipment details and rates

Rate Shopping

• Get shipping rates for shipments
• Compare rates across multiple carriers
• Live rate calculation at checkout

Label Generation

• Purchase shipping labels
• Generate labels in multiple formats (PDF, PNG, ZPL)
• Track label status and download URLs

Package Tracking

• Register tracking webhooks
• Get tracking status updates
• Monitor shipment progress

Carrier Management

• List available carrier accounts
• Manage carrier configurations
• Support for USPS, UPS, FedEx, DHL, and more

International Shipping

• Customs declarations
• International address validation
• Multi-country shipping support

Batch Operations

• Create and manage batch shipments
• Bulk label generation
• Batch processing for high-volume shipping

Security

API Key Management

• Test Keys: Use test API keys for development and testing
• Live Keys: Use live API keys only in production environments
• Never commit API keys to source control
• Environment Variables recommended for sensitive data

Getting Your API Key

1. Sign up at goshippo.com
2. Go to API Keys
3. Generate a key
4. Use it in your MCP configuration

Best Practices

• Use test keys during development
• Rotate keys regularly
• Never share keys publicly
• Store sensitive configuration in environment variables

Contributions

We welcome contributions! Please:

• Open issues for bug reports or feature requests
• Submit pull requests for improvements
• Share feedback and suggestions

Support

For support and questions:

• Check the Shippo API docs
• Contact Shippo support

About Shippo

Connect with multiple different 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.