# Taiwan Logistics MCP 🇹🇼 — How can my AI agent create a 超商取貨 / 宅配 shipment in Taiwan?

<!-- install-cta -->
## Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

```json
{
  "mcpServers": {
    "taiwan-logistics": {
      "type": "http",
      "url": "https://logi-tw.wishpool.app/mcp"
    }
  }
}
```

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the [threat model](https://mcp.wishpool.app/trust).

### Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/junter1989k-ai/taiwan-logistics-mcp)

```bash
git clone https://github.com/junter1989k-ai/taiwan-logistics-mcp && cd taiwan-logistics-mcp && npx vercel --prod
```

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

---

Remote MCP server that lets any AI agent create **Taiwan shipments** — 超商取貨 (CVS store pickup / 店到店: 7-11, 全家 FamilyMart, 萊爾富 Hi-Life, OK) and 宅配 (home delivery: 黑貓 TCAT, 中華郵政 POST) — print shipping labels (託運單) and track parcels via the [ECPay 綠界 Logistics API](https://developers.ecpay.com.tw/?p=10118). Stateless, bring-your-own credentials, never stores anything. **Zero-setup demo mode** on ECPay stage.

**Live endpoint:** `https://logi-tw.wishpool.app/mcp` · Registry: `app.wishpool/taiwan-logistics-mcp`

## Quick start

```json
{
  "mcpServers": {
    "taiwan-logistics": {
      "type": "http",
      "url": "https://logi-tw.wishpool.app/mcp",
      "headers": {
        "x-ecpay-merchant-id": "your-merchant-id",
        "x-ecpay-hash-key": "your-hash-key",
        "x-ecpay-hash-iv": "your-hash-iv"
      }
    }
  }
}
```

**No headers = demo mode.** The server falls back to ECPay's official public test merchant on the stage host, so `create_shipment` returns a real test `AllPayLogisticsID` and you can try the whole flow instantly. Add `"x-ecpay-mode": "production"` to hit the live host. The same ECPay triplet also powers [taiwan-payments-mcp](https://mcp.wishpool.app).

## Tools

| Tool | What it does |
|---|---|
| `create_shipment` | Create a 超商取貨 (CVS) or 宅配 (HOME) order. `logistics_type` CVS/HOME + `sub_type` (C2C: UNIMARTC2C/FAMIC2C/HILIFEC2C/OKMARTC2C · B2C: UNIMART/FAMI/HILIFE · HOME: TCAT/POST), `goods_amount`, sender/receiver name+phone, `receiver_store_id` for CVS or address+zip for HOME. `is_collection=true` = 代收貨款 (COD). Returns `AllPayLogisticsID` (as `shipment_id`). |
| `query_shipment` | Track by `shipment_id` — returns `status_code` + plain-English hint (300 created, 2063 shipped, 2067/3006 at store, 2073/3022 picked up, 5058 home delivered, …). |
| `print_label` | Returns a hosted `label_url` that auto-submits the signed ECPay print form for the 託運單 / 一段標. |

Owner policy guardrails ride optional headers (`x-agentpay-max-amount`, `x-agentpay-approval-above`, `x-agentpay-allowed-tools`) — set by the human owner in client config; the agent cannot relax them. Applied to goods / COD amounts.

## Develop

```bash
node test/serve.js   # local server on :3233 (/mcp + /label)
node test/e2e.js     # protocol + validation + AES/CheckMac unit test + REAL stage shipment
```

## How it talks to ECPay

`create_shipment` / `query_shipment` are **server-to-server form POSTs** to ECPay's `/Express/Create` and `/Helper/QueryLogisticsTradeInfo/V2`, signed with a **CheckMacValue (MD5, `quote_plus` + lowercase)** exactly as ECPay's official [Logistic_Python SDK](https://github.com/ECPay/Logistic_Python) does — not the AES v2 temp-trade envelope. `print_label` returns a URL to our `/label` page, which auto-submits a signed form to ECPay's `printTradeDocument` (browser POST, like the payments `/pay` pattern).

## Safety

Pure stateless translation layer. The 託運單 is generated and served by ECPay; the ECPay HashKey/HashIV travel per-request in headers, nothing is stored. Parcels flow sender ↔ ECPay/carrier ↔ receiver directly. [Privacy policy](https://logi-tw.wishpool.app/privacy).

## Sister servers

Taiwan payments **and 電子發票 (e-invoice)** — same ECPay merchant triplet — live in [taiwan-payments-mcp](https://mcp.wishpool.app). One family of stateless BYO local-commerce MCP servers: local payments in 81 countries, plus invoice servers for Mexico CFDI (inv-mx) · Brazil NF-e (inv-br) · Chile DTE (inv-cl) · Peru CPE (inv-pe) · India GST (inv-in).

MIT licensed.