Shipsaving

npm version License: MIT

中文文档

An MCP (Model Context Protocol) server that wraps the ShipSaving logistics REST API, enabling AI assistants like Claude to perform shipping operations through natural language.

Features

• Shipment Management — Multi-carrier rate comparison, create shipments, pay & generate labels, void labels, track packages
• Order Management — Sync store orders, search, bulk label printing, mark as shipped, cancel
• Address Book — Query, create, and validate addresses
• Package Templates — Save and reuse package dimensions
• Carriers — List connected carrier accounts and available service levels
• Store Integration — List connected e-commerce stores (Shopify, etc.)
• Analytics — Total savings, shipping cost analysis
• Billing — Wallet balance, transaction history

Quick Start

Prerequisites

• Node.js 18+
• A ShipSaving App Key (get one at ShipSaving → Settings → API)

Install with Claude Code CLI (Recommended)

claude mcp add shipsaving \
  -e SHIPSAVING_APP_KEY=sk_your_app_key \
  -- npx -y shipsaving-mcp

Install with Claude Desktop

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "shipsaving": {
      "command": "npx",
      "args": ["-y", "shipsaving-mcp"],
      "env": {
        "SHIPSAVING_APP_KEY": "sk_your_app_key"
      }
    }
  }
}

Restart Claude Desktop after saving.

Verify Installation

claude mcp list
# shipsaving should show status: Connected

Available Tools

Shipment Management

Tool	Description
get_shipping_rates	Compare rates across multiple carriers, marks cheapest & fastest
create_draft_shipment	Create a draft shipment (no payment yet)
pay_shipment	Pay for shipment and generate label
void_label	Void/refund an unused label
search_shipments	Search shipments by various criteria
get_shipment_detail	Get detailed shipment information
track_shipment	Track package by tracking number
get_insurance_rates	Query shipping insurance rates

Order Management

Tool	Description
search_orders	Search orders by status, store, date, keywords
get_order_detail	Get order details
create_order	Manually create an order
buy_label_from_order	Purchase a label for an existing order
mark_order_shipped	Mark order as shipped
cancel_order	Cancel an order
sync_store_orders	Trigger store order sync
get_order_tags	List all order tags

Address Book

Tool	Description
list_addresses	Query address book entries
create_address	Add a new address
update_address	Update an existing address
validate_address	Validate address deliverability

Package Templates

Tool	Description
list_packages	List saved package templates
list_predefined_packages	List carrier-provided package types
create_package	Create a reusable package template

Carriers & Stores

Tool	Description
list_carriers	List connected carrier accounts
get_service_levels	Query available service levels per carrier
list_stores	List connected e-commerce stores

Analytics & Billing

Tool	Description
get_total_savings	View total savings with ShipSaving
get_shipping_analysis	Analyze shipping data over time
get_wallet_info	Query wallet balance
get_transaction_history	Query transaction records

Usage Examples

Compare shipping rates:

Compare rates from ZIP 90001 to 10001 for a 10x8x6 inch, 2 lb package

Ship a package:

Ship from John Smith, 123 Main St, Los Angeles, CA 90001
to Jane Doe, 456 Park Ave, New York, NY 10001
Package: 10x8x6 inches, 2 lbs, choose cheapest option

Bulk label printing:

Sync my Shopify orders, then print labels for all pending orders
using 6x6x6 inch boxes, 1 lb each, cheapest carrier, no insurance

Track a package:

Track package 1Z999AA10123456784

Environment Variables

Variable	Required	Default	Description
SHIPSAVING_APP_KEY	Yes	—	ShipSaving App Key (sk_ prefix)
SHIPSAVING_API_BASE_URL	No	https://app-gateway.shipsaving.com	API base URL
SHIPSAVING_TIMEOUT_MS	No	60000	Request timeout in milliseconds
SHIPSAVING_LOG_FILE	No	—	Path to log file (logs go to stderr by default)

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Debug with MCP Inspector
SHIPSAVING_API_BASE_URL=https://app-gateway.shipsaving.com \
SHIPSAVING_APP_KEY=sk_your_app_key \
npx @modelcontextprotocol/inspector node dist/index.js

Troubleshooting

"command not found" — Install Node.js 18+: nodejs.org

"Failed to connect" — Try running the server manually to see error output:

SHIPSAVING_APP_KEY=sk_your_app_key npx -y shipsaving-mcp

If it hangs (waiting for input), the server started successfully. If it errors immediately, you'll see the issue.

To clear the npx cache:

rm -rf ~/.npm/_npx

License

MIT