ShipSaving

ShipSaving MCP 服务

中文文档

一个 MCP（Model Context Protocol）服务，封装了 ShipSaving 物流 REST API，让 Claude 等 AI 助手能够通过自然语言执行发货操作。

功能

• 货件管理 — 比较多个承运商的费率、创建货件、付款并生成标签、作废标签、追踪包裹
• 订单管理 — 同步店铺订单、搜索、批量打印标签、标记为已发货、取消
• 地址簿 — 查询、创建和验证地址
• 包裹模板 — 保存并重复使用包裹尺寸
• 承运商 — 列出已连接的承运商账户和可用服务等级
• 店铺集成 — 列出已连接的电商店铺（Shopify 等）
• 分析 — 总节省金额、运费分析
• 账单 — 钱包余额、交易记录

快速开始

前置条件

• Node.js 18+
• ShipSaving App Key（前往 ShipSaving → Settings → API 获取）

使用 Claude Code CLI 安装（推荐）

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

使用 Claude Desktop 安装

编辑配置文件：

• 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"
      }
    }
  }
}

保存后重启 Claude Desktop。

验证安装

claude mcp list
# shipsaving should show status: Connected

可用工具

货件管理

工具	说明
get_shipping_rates	比较多个承运商的费率，并标出最便宜和最快的选项
create_draft_shipment	创建货件草稿（暂不付款）
pay_shipment	支付货件费用并生成标签
void_label	作废／退款未使用的标签
search_shipments	按多种条件搜索货件
get_shipment_detail	获取货件详细信息
track_shipment	按追踪号追踪包裹
get_insurance_rates	查询运输保险费率

订单管理

工具	说明
search_orders	按状态、店铺、日期和关键词搜索订单
get_order_detail	获取订单详情
create_order	手动创建订单
buy_label_from_order	为现有订单购买标签
mark_order_shipped	将订单标记为已发货
cancel_order	取消订单
sync_store_orders	触发店铺订单同步
get_order_tags	列出所有订单标签

地址簿

工具	说明
list_addresses	查询地址簿条目
create_address	添加新地址
update_address	更新现有地址
validate_address	验证地址是否可配送

包裹模板

工具	说明
list_packages	列出已保存的包裹模板
list_predefined_packages	列出承运商提供的包裹类型
create_package	创建可重复使用的包裹模板

承运商和店铺

工具	说明
list_carriers	列出已连接的承运商账户
get_service_levels	查询各承运商可用的服务等级
list_stores	列出已连接的电商店铺

分析和账单

工具	说明
get_total_savings	查看使用 ShipSaving 节省的总金额
get_shipping_analysis	分析一段时间内的运输数据
get_wallet_info	查询钱包余额
get_transaction_history	查询交易记录

使用示例

比较运费：

Compare rates from ZIP 90001 to 10001 for a 10x8x6 inch, 2 lb 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

批量打印标签：

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

追踪包裹：

Track package 1Z999AA10123456784

环境变量

变量	必需	默认值	描述
SHIPSAVING_APP_KEY	是	—	ShipSaving App Key（前缀为 sk_）
SHIPSAVING_API_BASE_URL	否	https://app-gateway.shipsaving.com	API 基础 URL
SHIPSAVING_TIMEOUT_MS	否	60000	请求超时时间（毫秒）
SHIPSAVING_LOG_FILE	否	—	日志文件路径（默认将日志输出到 stderr）

开发

# 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

故障排除

“command not found” — 安装 Node.js 18+：nodejs.org

“Failed to connect” — 尝试手动运行服务以查看错误输出：

SHIPSAVING_APP_KEY=sk_your_app_key npx -y shipsaving-mcp

如果命令挂起（等待输入），说明服务已成功启动。如果立即报错，你将看到问题所在。

清除 npx 缓存：

rm -rf ~/.npm/_npx

许可证

MIT