Skip to main content
skill CX Codex

logistics-tracking — Claude Code skill: what it does, how to install

logistics-tracking tracks international shipments across 3100+ carriers using tracking numbers through 17track or a local Playwright fallback.

MIT 118 installs ★ 4 updated 2026-02-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add shopmeskills/mcp --skill logistics-tracking -a claude-code
Open on GitHub

What logistics-tracking does

This skill connects Claude Code to parcel tracking tools exposed by the @shopmeagent/logistics-tracking-mcp server. It provides four actions: single shipment updates via track_package, carrier identification via detect_carrier, batch tracking up to 40 parcels via batch_track, and human-readable shipping stages via explain_status.

You can query parcels with or without an API token. Supplying TRACK17_API_KEY queries the official 17track API across services like China Post, FedEx, and UPS. Without credentials, it scrapes tracking pages via headless Chromium, meaning requests immediately fail if the playwright npm package is not installed.

What it helps with

  • check delivery progress using a parcel tracking number
  • identify shipping couriers from tracking number formats
  • query up to 40 tracking numbers in a single request
  • explain international customs holds and logistics events

Example prompts for the agent

  • Where is my package LX123456789CN?
  • Detect carrier for 1ZABCDEF1234567890 and check status
  • Batch track shipments YT2412345678901234 and LP12345678901234

How to install logistics-tracking

1Skills CLI (Vercel)

npx skills add shopmeskills/mcp --skill logistics-tracking -a claude-code

2Manually: put the files in place

~/.claude/skills/logistics-tracking/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/logistics-tracking/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about logistics-tracking

How do I install logistics-tracking in Claude Code?

Run npx skills add shopmeskills/mcp --skill logistics-tracking -a claude-code in your terminal.

What does logistics-tracking do?

It looks up delivery progress for international parcels, identifies matching shipping carriers, and explains tracking status codes.

Is an API key required to track packages?

An API key is optional. Without TRACK17_API_KEY, the tool uses a browser fallback that requires the playwright package installed in your environment.

Source text

SKILL.md · MIT
---
name: logistics-tracking
description: >
  Track international packages by tracking number. Supports 3100+ carriers (China Post, DHL, FedEx, UPS, USPS, Yanwen, Cainiao, etc.) via 17track.
  Optional: set TRACK17_API_KEY for best results. Without a key, uses Playwright (headless browser) as fallback.
  Use when the user asks about package tracking, shipment status, delivery time, or logistics queries.
license: MIT
metadata:
  author: shopme
  version: "1.0.1"
  mcp-server: "@shopmeagent/logistics-tracking-mcp"
---

# Logistics Tracking

Track international packages by tracking number only. Supports 3100+ carriers worldwide.

## When to Use

- User asks "where is my package" or provides a tracking number
- User needs to check shipment status or delivery estimate
- User asks about customs clearance or logistics exceptions
- User needs to track multiple packages at once

## How It Works

| Mode | API Key Required? | Description |
|------|-------------------|-------------|
| **With TRACK17_API_KEY** | Yes (1 key) | Uses the official api.17track.net — most reliable, 3100+ carriers. |
| **Without key** | No | Uses Playwright (headless Chromium) to query t.17track.net. Requires `playwright` npm package. |

**Recommendation:** Set `TRACK17_API_KEY` for the best reliability. Get a free key at https://api.17track.net

## Option A: Deploy as HTTP Service (users need no key)

You deploy the MCP HTTP server with `TRACK17_API_KEY` on your server. End users connect via URL — they don't need any API key.

### 1. Start the server (your side)

```bash
export TRACK17_API_KEY=your-17track-api-key
npx -y @shopmeagent/logistics-tracking-mcp serve

# Default: http://0.0.0.0:3000/mcp
# Override with PORT and HOST env vars
```

### 2. User/client MCP config (Streamable HTTP)

```json
{
  "mcpServers": {
    "logistics-tracking": {
      "type": "streamable-http",
      "url": "https://your-domain.com/mcp"
    }
  }
}
```

Users only need a tracking number — no API key required on their end.

---

## Option B: Local stdio (zero-config or with key)

**Zero-config** (no key, uses Playwright fallback — requires `playwright` installed):

```json
{
  "mcpServers": {
    "logistics-tracking": {
      "command": "npx",
      "args": ["-y", "@shopmeagent/logistics-tracking-mcp"]
    }
  }
}
```

**Recommended** — with API key for broader carrier coverage and better reliability:

```json
{
  "mcpServers": {
    "logistics-tracking": {
      "command": "npx",
      "args": ["-y", "@shopmeagent/logistics-tracking-mcp"],
      "env": {
        "TRACK17_API_KEY": "your-17track-api-key"
      }
    }
  }
}
```

Get a free 17track API key: https://api.17track.net

## Using with OpenClaw

Add this skill to OpenClaw:

```bash
npx skills add shopmeskills/mcp
```

Then in OpenClaw's MCP configuration, add either the **HTTP** or **stdio** config shown above.

**Example prompts:**
- "Track package YT2412345678901234"
- "Where is my package LX123456789CN?"
- "Check status of 1ZABCDEF1234567890"

## Available Tools

### track_package
Query tracking info for a single package.
- Input: `trackingNumber` (required), `carrier` (optional, auto-detected)
- Returns: status, current location, timeline of events

### detect_carrier
Identify the carrier from a tracking number's format.
- Input: `trackingNumber`
- Returns: carrier name, confidence level

### batch_track
Track up to 40 packages at once.
- Input: `trackingNumbers` array
- Returns: array of tracking results

### explain_status
Get a human-readable explanation of a tracking status code.
- Input: `statusCode` (e.g. InTransit, CustomsClearance, Delivered)
- Returns: description and advice in English

## Tracking Number Format Guide

| Pattern | Carrier | Example |
|---------|---------|---------|
| `XX123456789CN` | China Post | LX123456789CN |
| `EX123456789CN` | China EMS | EA123456789CN |
| `YT + 16 digits` | Yanwen | YT1234567890123456 |
| `LP + 14+ digits` | Cainiao | LP12345678901234 |
| `SF + 12+ digits` | SF Express | SF1234567890123 |
| `1Z + 16 chars` | UPS | 1ZABCDEF1234567890 |
| `94/93/92 + 20 digits` | USPS | 9400111899223100012345 |
| `10-11 digits` | DHL | 1234567890 |
| `12-15 digits` | FedEx | 123456789012 |

## Typical Delivery Times (International)

| Route | Standard | Express |
|-------|----------|---------|
| China to US | 15-30 days | 5-10 days |
| China to EU | 15-30 days | 5-10 days |
| China to SE Asia | 7-15 days | 3-7 days |
| China to Japan/Korea | 5-10 days | 3-5 days |

## Status Codes Explained

- **InfoReceived**: Carrier has the info but hasn't picked up the package (1-3 day wait)
- **InTransit**: Package is moving through the logistics network
- **CustomsClearance**: Going through customs (3-7 business days typical)
- **OutForDelivery**: Final delivery attempt today
- **Delivered**: Successfully delivered
- **Exception**: Problem occurred (customs hold, wrong address, failed delivery)
- **Returned**: Being sent back to origin

## Tips

1. **No key needed**: Without TRACK17_API_KEY, the tool uses Playwright to query 17track directly. Install Playwright with `npm install playwright` for this to work.
2. **3100+ carriers**: With a 17track API key, auto-detects carrier from the tracking number.
3. Wait 24-48 hours after shipment before tracking — data may not be available on day one.
4. Allow at least 2 hours between queries for the same tracking number to avoid rate limiting.
5. Use `batch_track` for multiple packages — more efficient than individual queries.

© shopme · MIT · shopmeskills/mcp

Similar skills

All skills for Automation and no-code: n8n, Zapier, Make →

From the same set2

Project sponsors

Companies that keep this analytics open