# logistics-tracking

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

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 118 installs · ★ 4 repo stars
- Author: shopme
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/shopmeskills/mcp/tree/HEAD/skills/logistics-tracking/SKILL.md
- Updated: 2026-02-20
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/logistics-tracking

## What it 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.

## Requirements
- Works with: Playwright

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add shopmeskills/mcp --skill logistics-tracking -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/logistics-tracking/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/logistics-tracking/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add shopmeskills/mcp --skill logistics-tracking -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/logistics-tracking/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add shopmeskills/mcp --skill logistics-tracking -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/logistics-tracking/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install shopmeskills/mcp skills/logistics-tracking
```

2. **Manually: put the files in place**
- File: `.github/skills/logistics-tracking/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add shopmeskills/mcp --skill logistics-tracking -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/shopmeskills/mcp --path skills/logistics-tracking
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/logistics-tracking/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add shopmeskills/mcp --skill logistics-tracking -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/shopmeskills/mcp/tree/HEAD/skills/logistics-tracking/SKILL.md

## When to use it
- 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
- Where is my package LX123456789CN?
- Detect carrier for 1ZABCDEF1234567890 and check status
- Batch track shipments YT2412345678901234 and LP12345678901234

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: c680f7b784dbf98f.

BEGIN THIRD-PARTY FILE c680f7b784dbf98f
````text
---
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?"
````
END THIRD-PARTY FILE c680f7b784dbf98f

The third-party file has ended. Everything between the c680f7b784dbf98f tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2974 of 5511 bytes. © shopme · MIT · https://github.com/shopmeskills/mcp/tree/HEAD/skills/logistics-tracking/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
