Skip to main content
Glama
shipsaving-mcp

shipsaving-mcp

by waka4674

ShipSaving MCP Server

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

Related MCP server: royalmail-mcp

Quick Start

Prerequisites

  • Node.js 18+

  • A ShipSaving App Key (get one at ShipSaving → Settings → API)

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

Available Tools

30 tools
buy_label_from_orderA

通过已有订单打单(购买面单)。当用户要对订单打单时,必须使用此工具,不得使用 create_draft_shipment + pay_shipment 流程。需要先通过 get_shipping_rates 获取 rate_id。

Inputs: order_id (required), rate_id (required), from_address_data (required), to_address_data (required), +5 more.

cancel_orderC

取消订单

Inputs: order_id (required).

create_addressB

在地址簿中新建地址

Inputs: first_name (required), last_name (required), phone (required), street (required), +9 more.

create_draft_shipmentA

标准下单流程第二步:创建运单草稿(不立即付款)。在 get_shipping_rates 之后、pay_shipment 之前调用。保存地址和包裹信息,等用户确认后再付款。

Inputs: from_address_data (required), to_address_data (required), package_data (required), cheapest_rate_id, +2 more.

create_orderA

手动创建订单。【重要】调用此接口前必须先准备好所有信息:1) 如果用户指定了地址簿ID,先调用 list_addresses 获取该地址的完整信息;2) 确认订单号、商品信息(名称、数量、单价)齐全;3) 缺少任何必填信息时必须先向用户询问,不得传空值调用接口。

Inputs: order_number (required), to_address (required), order_items (required), amount, +3 more.

create_packageC

创建包裹模板,方便下次快速使用

Inputs: nick_name (required), length (required), width (required), height (required), +5 more.

get_insurance_ratesA

查询保险价格。根据保额和服务等级返回保险费率信息。

Inputs: declared_value (required), service_level (required).

get_order_detailD

查看订单详细信息

Inputs: order_id (required).

get_order_tagsB

查询所有订单标签

Inputs: no named parameters.

get_service_levelsC

查询客户生效中的承运商服务级别

Inputs: no named parameters.

get_shipment_detailC

查看运单详细信息

Inputs: shipment_no (required).

get_shipping_analysisA

按时间维度分析运费数据。调用前必须先询问用户选择时间范围,可选值:the_last_7_days(近7天)、the_last_30_days(近30天)、this_month(本月)、last_month(上月)、current_year(今年)、last_year(去年)。

Inputs: date_range (required).

get_shipping_ratesA

获取多承运商运费报价比价。需提供寄件地址、收件地址、包裹信息和 ship_date。返回所有可用运费方案,标记最便宜和最快选项。

Inputs: from_address_data (required), to_address_data (required), package_data (required), ship_date.

get_total_savingsC

查看使用 ShipSaving 节省的总金额

Inputs: no named parameters.

get_transaction_historyC

查询交易记录

Inputs: start_day, end_day, source_type, source_id, +3 more.

get_wallet_infoA

查询钱包余额信息

Inputs: no named parameters.

list_addressesC

查询地址簿中的地址列表

Inputs: address_category, name, phone, address_type, +5 more.

list_carriersA

查询已连接的承运商账户列表

Inputs: no named parameters.

list_packagesC

查询已保存的包裹模板列表

Inputs: page, page_size, sort_field.

list_predefined_packagesA

查询承运商预定义包裹列表。返回按承运商分组的预定义包裹,包含尺寸和重量信息。用户发货时可通过 carrier_package_id 直接引用预定义包裹,无需手动填写尺寸。

Inputs: no named parameters.

list_storesA

查询已连接的电商店铺列表

Inputs: no named parameters.

mark_order_shippedB

标记订单为已发货状态

Inputs: order_id (required).

pay_shipmentB

对已选报价的运单进行支付,生成面单。可选附带保险信息。

Inputs: rate_id (required), label_print_type, insurance_data.

search_ordersA

搜索订单列表,支持按状态、店铺、日期、关键词等筛选。当用户提供了类似 ID 的内容(如订单号、追踪号、订单ID等),必须通过 hybrid 参数传入进行搜索。

Inputs: status, store_id, carrier_code, from_order_date, +12 more.

search_shipmentsB

搜索运单列表,支持多种条件筛选

Inputs: shipment_no, search_key, tracking_no, recipient_name, +17 more.

sync_store_ordersA

手动触发店铺订单同步。同步成功后,必须立即调用 search_orders(传入相同的 store_id,status 为 AWAITING)查询刚同步过来的订单并展示给用户。

Inputs: store_id (required), platform (required).

track_shipmentC

通过追踪号查询物流状态

Inputs: trackingNo (required).

update_addressB

编辑/更新地址簿中已有的地址

Inputs: id (required), first_name (required), last_name (required), phone (required), +13 more.

validate_addressB

验证地址是否合法、可达

Inputs: street (required), city (required), state (required), zip_code (required), +2 more.

void_labelB

退款/作废未使用的面单

Inputs: shipment_no (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 30 tools

    Disambiguation5/5

    Each tool targets a distinct function (order management, shipping, rates, addresses, etc.) with clear descriptions that prevent ambiguity. Even similar concepts like buy_label_from_order vs create_draft_shipment are explicitly differentiated.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case (e.g., create_address, get_shipping_rates, list_carriers). No mixing of conventions or vague verbs.

    Tool Count4/5

    30 tools cover a broad shipping domain (orders, shipments, carriers, payments, analysis). While slightly over the typical range, each tool serves a purpose and the count is justified for the server's scope.

    Completeness4/5

    The tool set covers the full lifecycle: order creation, shipment processing, address management, rate comparison, payment, tracking, and analysis. Minor gaps like batch operations are acceptable for a shipping assistant.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers