{
  "markdown": "# ShipSaving MCP Server\n\n[![npm version](https://img.shields.io/npm/v/shipsaving-mcp.svg)](https://www.npmjs.com/package/shipsaving-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[中文文档](./README.zh-CN.md)\n\nAn MCP (Model Context Protocol) server that wraps the [ShipSaving](https://www.shipsaving.com) logistics REST API, enabling AI assistants like Claude to perform shipping operations through natural language.\n\n## Features\n\n- **Shipment Management** — Multi-carrier rate comparison, create shipments, pay & generate labels, void labels, track packages\n- **Order Management** — Sync store orders, search, bulk label printing, mark as shipped, cancel\n- **Address Book** — Query, create, and validate addresses\n- **Package Templates** — Save and reuse package dimensions\n- **Carriers** — List connected carrier accounts and available service levels\n- **Store Integration** — List connected e-commerce stores (Shopify, etc.)\n- **Analytics** — Total savings, shipping cost analysis\n- **Billing** — Wallet balance, transaction history\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 18+\n- A ShipSaving App Key (get one at [ShipSaving](https://www.shipsaving.com) → Settings → API)\n\n### Install with Claude Code CLI (Recommended)\n\n```bash\nclaude mcp add shipsaving \\\n  -e SHIPSAVING_APP_KEY=sk_your_app_key \\\n  -- npx -y shipsaving-mcp\n```\n\n### Install with Claude Desktop\n\nEdit your config file:\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"shipsaving\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"shipsaving-mcp\"],\n      \"env\": {\n        \"SHIPSAVING_APP_KEY\": \"sk_your_app_key\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\n### Verify Installation\n\n```bash\nclaude mcp list\n# shipsaving should show status: Connected\n```\n\n## Available Tools\n\n### Shipment Management\n\n| Tool | Description |\n|------|-------------|\n| `get_shipping_rates` | Compare rates across multiple carriers, marks cheapest & fastest |\n| `create_draft_shipment` | Create a draft shipment (no payment yet) |\n| `pay_shipment` | Pay for shipment and generate label |\n| `void_label` | Void/refund an unused label |\n| `search_shipments` | Search shipments by various criteria |\n| `get_shipment_detail` | Get detailed shipment information |\n| `track_shipment` | Track package by tracking number |\n| `get_insurance_rates` | Query shipping insurance rates |\n\n### Order Management\n\n| Tool | Description |\n|------|-------------|\n| `search_orders` | Search orders by status, store, date, keywords |\n| `get_order_detail` | Get order details |\n| `create_order` | Manually create an order |\n| `buy_label_from_order` | Purchase a label for an existing order |\n| `mark_order_shipped` | Mark order as shipped |\n| `cancel_order` | Cancel an order |\n| `sync_store_orders` | Trigger store order sync |\n| `get_order_tags` | List all order tags |\n\n### Address Book\n\n| Tool | Description |\n|------|-------------|\n| `list_addresses` | Query address book entries |\n| `create_address` | Add a new address |\n| `update_address` | Update an existing address |\n| `validate_address` | Validate address deliverability |\n\n### Package Templates\n\n| Tool | Description |\n|------|-------------|\n| `list_packages` | List saved package templates |\n| `list_predefined_packages` | List carrier-provided package types |\n| `create_package` | Create a reusable package template |\n\n### Carriers & Stores\n\n| Tool | Description |\n|------|-------------|\n| `list_carriers` | List connected carrier accounts |\n| `get_service_levels` | Query available service levels per carrier |\n| `list_stores` | List connected e-commerce stores |\n\n### Analytics & Billing\n\n| Tool | Description |\n|------|-------------|\n| `get_total_savings` | View total savings with ShipSaving |\n| `get_shipping_analysis` | Analyze shipping data over time |\n| `get_wallet_info` | Query wallet balance |\n| `get_transaction_history` | Query transaction records |\n\n## Usage Examples\n\n**Compare shipping rates:**\n```\nCompare rates from ZIP 90001 to 10001 for a 10x8x6 inch, 2 lb package\n```\n\n**Ship a package:**\n```\nShip from John Smith, 123 Main St, Los Angeles, CA 90001\nto Jane Doe, 456 Park Ave, New York, NY 10001\nPackage: 10x8x6 inches, 2 lbs, choose cheapest option\n```\n\n**Bulk label printing:**\n```\nSync my Shopify orders, then print labels for all pending orders\nusing 6x6x6 inch boxes, 1 lb each, cheapest carrier, no insurance\n```\n\n**Track a package:**\n```\nTrack package 1Z999AA10123456784\n```\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `SHIPSAVING_APP_KEY` | Yes | — | ShipSaving App Key (`sk_` prefix) |\n| `SHIPSAVING_API_BASE_URL` | No | `https://app-gateway.shipsaving.com` | API base URL |\n| `SHIPSAVING_TIMEOUT_MS` | No | `60000` | Request timeout in milliseconds |\n| `SHIPSAVING_LOG_FILE` | No | — | Path to log file (logs go to stderr by default) |\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Watch mode\nnpm run dev\n\n# Debug with MCP Inspector\nSHIPSAVING_API_BASE_URL=https://app-gateway.shipsaving.com \\\nSHIPSAVING_APP_KEY=sk_your_app_key \\\nnpx @modelcontextprotocol/inspector node dist/index.js\n```\n\n## Troubleshooting\n\n**\"command not found\"** — Install Node.js 18+: [nodejs.org](https://nodejs.org)\n\n**\"Failed to connect\"** — Try running the server manually to see error output:\n\n```bash\nSHIPSAVING_APP_KEY=sk_your_app_key npx -y shipsaving-mcp\n```\n\nIf it hangs (waiting for input), the server started successfully. If it errors immediately, you'll see the issue.\n\nTo clear the npx cache:\n```bash\nrm -rf ~/.npm/_npx\n```\n\n## License\n\nMIT\n",
  "bytes": 5780,
  "sha": "cf9079b3cbe924679c6f2658f2a228d39a12e22a657141c68687edb0de4d96e4",
  "repo_slug": "waka4674/shipsaving-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_waka4674_shipsaving_mcp_e424bbd5/readme"
}