Taiwan Logistics (CVS pickup + home delivery via ECPay)

Official3 toolsLive

by junter1989k-ai · JavaScript

Taiwan CVS pickup + home delivery for AI agents: create, track, print labels via ECPay.

Topics

ai-agentsecpaylogisticsmcpmcp-servershippingtaiwancvs-pickupai-agentclaudewishpool

Captured live from the server via tools/list.

create_shipment

Create a Taiwan shipment via ECPay 綠界 Logistics — either 超商取貨 (CVS convenience-store pickup: 7-11 / 全家 FamilyMart / 萊爾富 Hi-Life / OK) or 宅配 (home delivery: 黑貓 TCAT / 中華郵政 POST). Bring your own ECPay credentials via headers x-ecpay-merchant-id, x-ecpay-hash-key, x-ecpay-hash-iv (+ x-ecpay-mode: production to hit the live host). With NO credential headers it runs in DEMO mode on ECPay stage using the official public test merchant — a real test AllPayLogisticsID is returned but nothing ships. logistics_type CVS needs receiver_store_id (a store code from ECPay電子地圖; the stage demo defaults to test store 131386). logistics_type HOME needs sender/receiver address + zip. Set is_collection=true for cash-on-delivery (代收貨款) — collection_amount defaults to goods_amount. Returns AllPayLogisticsID (as shipment_id) used by query_shipment and print_label.

Parameters19

logistics_type	string	required	CVS = 超商取貨 (store pickup); HOME = 宅配 (home delivery). Must match sub_type.
sub_type	string	required	Carrier/flow. CVS C2C (individual seller): UNIMARTC2C(7-11) / FAMIC2C / HILIFEC2C / OKMARTC2C. CVS B2C (business): UNIMART / FAMI / HILIFE. HOME: TCAT(黑貓) / POST(郵局).
goods_amount	integer	required	Declared goods value in TWD (integer). Also the COD amount when is_collection=true.
goods_name	string	optional	Goods description (<=50 chars). Default "商品一批".
is_collection	boolean	optional	true = cash-on-delivery 代收貨款 (buyer pays at pickup). Default false. collection_amount defaults to goods_amount.
collection_amount	integer	optional	COD amount in TWD (only when is_collection=true). Defaults to goods_amount.
sender_name	string	required	Sender name (寄件人, <=10 chars, no digits/symbols).
sender_phone	string	optional	Sender landline or mobile (擇一必填 with sender_cellphone).
sender_cellphone	string	optional	Sender mobile 09xxxxxxxx.
receiver_name	string	required	Receiver name (收件人, <=10 chars, no digits/symbols).
receiver_phone	string	optional	Receiver landline.
receiver_cellphone	string	optional	Receiver mobile 09xxxxxxxx (required for CVS pickup SMS notification).
receiver_email	string	optional	Optional receiver email.
receiver_store_id	string	optional	CVS only: pickup store code from ECPay電子地圖. Demo/stage defaults to test store 131386.
sender_zip	string	optional	HOME only: sender postal code.
sender_address	string	optional	HOME only: sender full address.
receiver_zip	string	optional	HOME only: receiver postal code.
receiver_address	string	optional	HOME only: receiver full address.
server_reply_url	string	optional	Optional server-to-server status callback URL (ECPay posts logistics updates here). A placeholder is used if omitted.

Raw schema

{
  "type": "object",
  "properties": {
    "logistics_type": {
      "type": "string",
      "enum": [
        "CVS",
        "HOME"
      ],
      "description": "CVS = 超商取貨 (store pickup); HOME = 宅配 (home delivery). Must match sub_type."
    },
    "sub_type": {
      "type": "string",
      "enum": [
        "UNIMARTC2C",
        "FAMIC2C",
        "HILIFEC2C",
        "OKMARTC2C",
        "UNIMART",
        "FAMI",
        "HILIFE",
        "TCAT",
        "POST"
      ],
      "description": "Carrier/flow. CVS C2C (individual seller): UNIMARTC2C(7-11) / FAMIC2C / HILIFEC2C / OKMARTC2C. CVS B2C (business): UNIMART / FAMI / HILIFE. HOME: TCAT(黑貓) / POST(郵局)."
    },
    "goods_amount": {
      "type": "integer",
      "description": "Declared goods value in TWD (integer). Also the COD amount when is_collection=true."
    },
    "goods_name": {
      "type": "string",
      "description": "Goods description (<=50 chars). Default \"商品一批\"."
    },
    "is_collection": {
      "type": "boolean",
      "description": "true = cash-on-delivery 代收貨款 (buyer pays at pickup). Default false. collection_amount defaults to goods_amount."
    },
    "collection_amount": {
      "type": "integer",
      "description": "COD amount in TWD (only when is_collection=true). Defaults to goods_amount."
    },
    "sender_name": {
      "type": "string",
      "description": "Sender name (寄件人, <=10 chars, no digits/symbols)."
    },
    "sender_phone": {
      "type": "string",
      "description": "Sender landline or mobile (擇一必填 with sender_cellphone)."
    },
    "sender_cellphone": {
      "type": "string",
      "description": "Sender mobile 09xxxxxxxx."
    },
    "receiver_name": {
      "type": "string",
      "description": "Receiver name (收件人, <=10 chars, no digits/symbols)."
    },
    "receiver_phone": {
      "type": "string",
      "description": "Receiver landline."
    },
    "receiver_cellphone": {
      "type": "string",
      "description": "Receiver mobile 09xxxxxxxx (required for CVS pickup SMS notification)."
    },
    "receiver_email": {
      "type": "string",
      "description": "Optional receiver email."
    },
    "receiver_store_id": {
      "type": "string",
      "description": "CVS only: pickup store code from ECPay電子地圖. Demo/stage defaults to test store 131386."
    },
    "sender_zip": {
      "type": "string",
      "description": "HOME only: sender postal code."
    },
    "sender_address": {
      "type": "string",
      "description": "HOME only: sender full address."
    },
    "receiver_zip": {
      "type": "string",
      "description": "HOME only: receiver postal code."
    },
    "receiver_address": {
      "type": "string",
      "description": "HOME only: receiver full address."
    },
    "server_reply_url": {
      "type": "string",
      "description": "Optional server-to-server status callback URL (ECPay posts logistics updates here). A placeholder is used if omitted."
    }
  },
  "required": [
    "logistics_type",
    "sub_type",
    "goods_amount",
    "sender_name",
    "receiver_name"
  ]
}

query_shipment

Look up a Taiwan shipment created by create_shipment, by its AllPayLogisticsID (shipment_id). Returns the current logistics status_code + a plain-English hint. Common codes: 300 order created; 2030 waiting for seller drop-off (CVS C2C); 2063 shipped; 2067/3006 arrived at store waiting for buyer; 2073/3022 picked up (delivered); 2074 returned (not collected in time); 5002 home delivery in transit; 5058 home delivered. Raw ECPay fields are always included. Safe to call anytime. Same credential/demo rules as create_shipment.

Parameters2

shipment_id	string	required	The AllPayLogisticsID (shipment_id) returned by create_shipment.
c2c	boolean	optional	In DEMO mode only: set true if the shipment was a CVS C2C order (uses the C2C test merchant). Ignored when your own credentials are sent.

Raw schema

{
  "type": "object",
  "properties": {
    "shipment_id": {
      "type": "string",
      "description": "The AllPayLogisticsID (shipment_id) returned by create_shipment."
    },
    "c2c": {
      "type": "boolean",
      "description": "In DEMO mode only: set true if the shipment was a CVS C2C order (uses the C2C test merchant). Ignored when your own credentials are sent."
    }
  },
  "required": [
    "shipment_id"
  ]
}

print_label

Get a hosted URL that renders and auto-submits the ECPay print form for a shipment's 託運單 / 一段標 (shipping label / drop-off slip), by AllPayLogisticsID. Open the returned label_url in a browser to view/print the label served by ECPay (the label is generated by ECPay; this server only signs the form and never stores it). For CVS C2C 小白單/繳款單 you also need the cvs_payment_no returned by create_shipment. Same credential/demo rules as create_shipment.

Parameters2

shipment_id	string	required	The AllPayLogisticsID (shipment_id) returned by create_shipment.
c2c	boolean	optional	In DEMO mode only: set true if the shipment was a CVS C2C order. Ignored when your own credentials are sent.

Raw schema

{
  "type": "object",
  "properties": {
    "shipment_id": {
      "type": "string",
      "description": "The AllPayLogisticsID (shipment_id) returned by create_shipment."
    },
    "c2c": {
      "type": "boolean",
      "description": "In DEMO mode only: set true if the shipment was a CVS C2C order. Ignored when your own credentials are sent."
    }
  },
  "required": [
    "shipment_id"
  ]
}

README.md5 KBView on GitHub

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

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.

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:

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. 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.

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 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.

Sister servers

Taiwan payments and 電子發票 (e-invoice) — same ECPay merchant triplet — live in taiwan-payments-mcp. 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.

Install

Tools (3)

create_shipmentquery_shipmentprint_label

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://logi-tw.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "taiwan-logistics-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://logi-tw.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.