npm package: @shippo/shippo-mcp
Description: Model Context Protocol (MCP) Server for the Shippo API.
Author: shippo
Latest version: 2.0.18

# <img src="https://docs.goshippo.com/images/Logo.png" width="30" alt="Shippo logo"> Shippo MCP Server

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

<div align="left">
    <a href="https://www.speakeasy.com/?utm_source=mcp&utm_campaign=mcp-typescript"><img src="https://custom-icon-badges.demolab.com/badge/-Built%20By%20Speakeasy-212015?style=for-the-badge&logoColor=FBE331&logo=speakeasy&labelColor=545454" /></a>
</div>


You must register for a [Shippo account](https://apps.goshippo.com/join) 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](https://docs.goshippo.com/docs/guides_general/authentication/). Replace `YOUR_SHIPPO_API_KEY` with your own token (including the `ShippoToken ` prefix) in the examples below.

<!-- Start Summary [summary] -->
## Summary

Shippo MCP Server: Use this MCP Server to integrate with the Shippo service using natural language and agentic flows.
<!-- End Summary [summary] -->

## Requirements

- **Node.js 18+** — [Download Node.js](https://nodejs.org/en/download)

<!-- Start Table of Contents [toc] -->
## Table of Contents
<!-- $toc-max-depth=2 -->
* [<img src="https://docs.goshippo.com/images/Logo.png" width="30" alt="Shippo logo"> Shippo MCP Server](#img-srchttpsdocsgoshippocomimageslogopng-width30-altshippo-logo-shippo-mcp-server)
  * [Requirements](#requirements)
  * [Quick Start](#quick-start)
  * [Configuration](#configuration)
  * [Updating](#updating)
  * [Troubleshooting](#troubleshooting)
  * [Features](#features)
  * [Security](#security)
  * [Contributions](#contributions)
  * [Support](#support)
  * [About Shippo](#about-shippo)

<!-- End Table of Contents [toc] -->

<!-- Start Installation [installation] -->
## Quick Start

<details>
<summary>Cursor</summary>

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=shippo-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzaGlwcG8vc2hpcHBvLW1jcCIsInN0YXJ0IiwiLS1hcGkta2V5LWhlYWRlciIsIlNoaXBwb1Rva2VuIFlPVVJfU0hJUFBPX0FQSV9LRVkiLCItLXNoaXBwby1hcGktdmVyc2lvbiIsIjIwMTgtMDItMDgiXX0=)

> ⚠️ **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:

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

</details>

<details>
<summary>Claude Code CLI</summary>

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

</details>

<details>
<summary>Claude Desktop</summary>

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

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

</details>


<details>
<summary> Manual CLI usage </summary>

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

```bash
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:

```bash
npx @shippo/shippo-mcp --help
```

</details>
<!-- End Installation [installation] -->

<!-- Start Configuration [configuration] -->

## Configuration

### Cursor / Claude

```json
{
  "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

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

<details>
<summary>Development</summary>

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:

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

</details>

<!-- End Configuration [configuration] -->

<!-- Start Updating [updating] -->

## Updating

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

### Check Current Version

```bash
npx @shippo/shippo-mcp --version
```

### Update to Latest Version

```bash
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.

<!-- End Updating [updating] -->

## 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):**

```bash
# 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:

```bash
npm install -g @shippo/shippo-mcp
```

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

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

<!-- Start Features [features] -->

## 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
  <!-- End Features [features] -->

<!-- Start Security [security] -->

## 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](https://goshippo.com)
2. Go to [API Keys](https://apps.goshippo.com/api)
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
  <!-- End Security [security] -->

## 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](https://docs.goshippo.com)
- Contact [Shippo support](https://goshippo.com/contact/)

## 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.
<!-- Placeholder for Future Speakeasy SDK Sections -->