Parcel Pilot MCP

Parcel Pilot MCP uses Playwright Chromium to save your personal browser login state, and then provides package data to AI clients via MCP. You can ask questions like this:

查询我所有待收货快递
今天有没有已经签收的包裹？
帮我查一下上周淘宝订单的物流进度

It is suitable for personal use and can run locally on a Mac or on your own Linux server. It is not an official open API integration for Taobao, JD, or Cainiao.

Key Features

Related MCP server: Parcel MCP Server

Response Example

{
  "packages": [
    {
      "id": "taobao-1234567890",
      "source": "taobao",
      "title": "USB-C 数据线",
      "status": "in_transit",
      "carrier": "菜鸟",
      "trackingNumber": "YT123456789CN",
      "lastEvent": "运输中预计今天送达",
      "updatedAt": "2026-05-08T09:00:00.000+08:00"
    }
  ]
}

Platform Status

E-commerce site pages change frequently, and parsers will need to be maintained based on actual page structures.

Quick Start

npm install
npm run build

Playwright installs Chromium during npm install. If system dependencies are missing on Linux, you can run:

npx playwright install-deps chromium

Copy .env.example to .env:

PACKAGE_ASSISTANT_DATA_DIR=./data
PACKAGE_ASSISTANT_PROFILE_DIR=./browser-profiles
PACKAGE_ASSISTANT_ARTIFACT_DIR=./var
PACKAGE_ASSISTANT_HEADLESS=true
PACKAGE_ASSISTANT_TIMEZONE=Asia/Shanghai

For the first login on macOS, it is recommended to open a visible browser:

PACKAGE_ASSISTANT_HEADLESS=false node dist/cli/open-login-browser.js taobao

After scanning the QR code and completing necessary verification, sync and query:

node dist/cli/call-tool.js sync_packages '{"source":"taobao"}'
node dist/cli/call-tool.js get_my_packages
node dist/cli/call-tool.js track_package '{"packageId":"taobao-ORDER_ID"}'

MCP Client Configuration

Any client that supports MCP stdio can be configured as follows:

{
  "mcpServers": {
    "parcel-pilot": {
      "command": "node",
      "args": ["/absolute/path/parcel-pilot-mcp/dist/server.js"],
      "env": {
        "PACKAGE_ASSISTANT_DATA_DIR": "/absolute/path/parcel-pilot-mcp/data",
        "PACKAGE_ASSISTANT_PROFILE_DIR": "/absolute/path/parcel-pilot-mcp/browser-profiles",
        "PACKAGE_ASSISTANT_ARTIFACT_DIR": "/absolute/path/parcel-pilot-mcp/var",
        "PACKAGE_ASSISTANT_HEADLESS": "true",
        "PACKAGE_ASSISTANT_TIMEZONE": "Asia/Shanghai"
      }
    }
  }
}

Initial Login Process

1. Have the AI client call login_taobao, login_jd, or login_cainiao.

2. Open the returned screenshotPath, usually located under var/login/.

3. Scan the QR code with your phone to log in.

4. Manually complete any CAPTCHAs, SMS, sliders, or risk alerts.

5. Call sync_packages.

6. You can now ask get_my_packages, track_package, or get_delivered_today.

If the QR code screenshot expires too quickly, or if the login page requires interaction, you can open a visible browser via noVNC, SSH X forwarding, or a desktop session:

PACKAGE_ASSISTANT_HEADLESS=false npm run dev

MCP Tools

Private Linux Server Deployment

Recommended setup:

• Docker and Docker Compose.

• Access only via SSH.

• MCP is started by an AI client on the same machine via stdio, or used via SSH/VPN.

• No public, unauthenticated HTTP entry points.

Deploying from local machine:

./scripts/aliyun-deploy.sh user@your-server:/opt/parcel-pilot-mcp

Perform one-time login and sync on the server:

cd /opt/parcel-pilot-mcp
docker compose run --rm -T package-assistant node dist/cli/call-tool.js login_taobao
docker compose run --rm -T package-assistant node dist/cli/call-tool.js login_jd
docker compose run --rm -T package-assistant node dist/cli/call-tool.js login_cainiao
docker compose run --rm -T package-assistant node dist/cli/call-tool.js sync_packages

For an interactive remote browser:

cd /opt/parcel-pilot-mcp
docker compose run --rm --service-ports package-assistant ./scripts/remote-browser.sh taobao
ssh -N -L 6080:127.0.0.1:6080 user@your-server

Then open:

http://127.0.0.1:6080/vnc.html?autoconnect=true&resize=scale

Call the MCP on the server via SSH:

{
  "mcpServers": {
    "parcel-pilot": {
      "command": "ssh",
      "args": [
        "user@your-server",
        "cd /opt/parcel-pilot-mcp && docker compose run --rm -T package-assistant"
      ]
    }
  }
}

Security Model

Treat browser-profiles/ as a "logged-in browser" and protect it accordingly.

• Do not commit data/, var/, browser-profiles/, .env, or tmp-login/.

• Do not expose the MCP process, noVNC, or temporary login browsers to the public internet.

• Recommended only for your own accounts and machines you control.

• Anyone with access to the browser profile may be able to view orders, logistics, shipping addresses, and account pages.

• This project does not bypass CAPTCHAs, sliders, SMS verification, or platform risk controls.

• It is recommended to disable low-friction payment/ordering features like small-amount password-free payments, auto-deductions, or express ordering to reduce risks if the login state is misused.

Development

npm test
npm run build

Common local commands:

npm run call-tool -- get_my_packages
npm run call-tool -- sync_packages '{"source":"taobao"}'

Roadmap

• Refine JD and Cainiao selectors using more real account pages.

• Add optional desensitization for sensitive fields like product names and addresses.

• Add provider health diagnostics for expired login states, risk pages, or empty pages.

• Add configuration examples for MCP clients like Claude Desktop, Codex, etc.

License

MIT