ECPay Logistics 綠界物流

Released已發布

ecommerce taiwan

MCP Server for ECPay logistics integration API — 3 tools for creating, querying, and cancelling logistics orders for convenience store pickup services.

綠界物流 MCP Server — 3 個工具：建立物流訂單、查詢訂單狀態、取消超商 C2C 訂單。

Status狀態

released

Tools工具數

Category分類

ecommerce

Region地區

taiwan

Maintainer維護者

@asgard-ai-platform

GitHub

Features功能特色

Three MCP tools — create, query, and cancel ECPay logistics orders
stdio JSON-RPC 2.0 — standard MCP transport protocol
@mcp.tool() decorator — typed tool registration with structured dict output
Legacy Form + MD5 signing — wraps ECPay's CheckMacValue flow for old logistics endpoints
Stage / production switch — controlled by ECPAY_ENV
Live smoke test support — probe the real API and exercise the tools against valid credentials

三個 MCP 工具 — 建立、查詢、取消綠界物流訂單
stdio JSON-RPC 2.0 — 標準 MCP 傳輸協定
@mcp.tool() 裝飾器 — 型別化工具註冊，回傳結構化 dict
Legacy Form + MD5 signing — 封裝綠界物流舊制 CheckMacValue 流程
stage / prod 切換 — 由 ECPAY_ENV 控制
支援 live smoke test — 可打真實 API 驗證連線與工具行為

Available Tools可用工具

Tool	Description
`create_logistics_order`	Create an ECPay logistics order with signed legacy payload. Expects a `payload` object containing business fields such as `MerchantTradeNo`, `MerchantTradeDate`, `LogisticsType`, `LogisticsSubType`, `GoodsAmount`, `SenderName`, `ReceiverName`, and `ServerReplyURL`.
`query_logistics_order`	Query an ECPay logistics order by `merchant_trade_no` or `allpay_logistics_id`, plus a required `timestamp`. Returns structured status fields such as `logistics_status`, `shipment_no`, and raw parsed `data`.
`cancel_logistics_order`	Cancel a C2C logistics order by `allpay_logistics_id`, `cvs_payment_no`, and `cvs_validation_no`. Returns `{ok, result, allpay_logistics_id}`.

You： 幫我在 stage 建一筆超商物流訂單。

AI call： ecpay-logistics - create_logistics_order (MCP)(payload: {"MerchantTradeNo": "LOG202605040001", "MerchantTradeDate": "2026/05/04 12:00:00", "LogisticsType": "CVS", "LogisticsSubType": "UNIMARTC2C", "GoodsAmount": 100, "GoodsName": "Demo Item", "SenderName": "Alice", "SenderCellPhone": "0912345678", "ReceiverName": "Bob", "ReceiverCellPhone": "0987654321", "ReceiverStoreID": "131386", "ServerReplyURL": "https://example.com/ecpay/callback"})

{
  "ok": true,
  "endpoint": "create_logistics_order",
  "rtn_code": "1",
  "rtn_msg": "OK",
  "allpay_logistics_id": "1234567",
  "merchant_trade_no": "LOG202605040001",
  "data": {
    "RtnCode": "1",
    "RtnMsg": "OK"
  }
}

Result： 綠界已接受這筆物流訂單，並回傳 AllPayLogisticsID。

You： 過一段時間幫我查這筆物流訂單狀態。

AI call： ecpay-logistics - query_logistics_order (MCP)(merchant_trade_no: "LOG202605040001", timestamp: 1714824000)

{
  "ok": true,
  "endpoint": "query_logistics_order",
  "logistics_status": "300",
  "allpay_logistics_id": "1234567",
  "merchant_trade_no": "LOG202605040001",
  "shipment_no": "ABC123456789",
  "data": {
    "LogisticsStatus": "300"
  }
}

Result： Tool 已回傳目前解析後的綠界物流狀態與關鍵託運識別資料。

You： 幫我取消這筆 C2C 物流訂單。

AI call： ecpay-logistics - cancel_logistics_order (MCP)(allpay_logistics_id: "1234567", cvs_payment_no: "CVS123", cvs_validation_no: "VAL456")

{
  "ok": true,
  "endpoint": "cancel_logistics_order",
  "result": "1|OK",
  "allpay_logistics_id": "1234567"
}

Result： 綠界已確認這筆 C2C 物流訂單的取消請求。

Development開發

# Setup
uv sync
cp .env.example .env

# Connection check
uv run --env-file .env python scripts/auth/test_connection.py

# Tool E2E / smoke tests
uv run python tests/test_all_tools.py

# Run server locally
uv run --env-file .env mcp-ecpay-logistics

See tests/test_all_tools.py for live examples of tool invocations and scripts/auth/test_connection.py for a minimal reachability probe.

# Setup
uv sync
cp .env.example .env

# Connection check
uv run --env-file .env python scripts/auth/test_connection.py

# Tool E2E / smoke tests
uv run python tests/test_all_tools.py

# Run server locally
uv run --env-file .env mcp-ecpay-logistics

tests/test_all_tools.py 內含 live tool invocation 範例；scripts/auth/test_connection.py 則是最小可達性檢查。

License授權

MIT License — see LICENSE for details.

MIT License — 詳見 LICENSE。

RequirementsRequirements

Python 3.10+
One of: uv (recommended) or pip
ECPay logistics credentials (ECPAY_MERCHANT_ID, ECPAY_HASH_KEY, ECPAY_HASH_IV)

Python 3.10+
uv（建議）或 pip
綠界物流商店參數（ECPAY_MERCHANT_ID、ECPAY_HASH_KEY、ECPAY_HASH_IV）

InstallInstall

Option 1 — `uvx` (no install, runs on demand)

uvx mcp-ecpay-logistics

Option 2 — `pip` / `uv pip`

pip install mcp-ecpay-logistics
# or
uv pip install mcp-ecpay-logistics

After install, the mcp-ecpay-logistics console script is available.

Option 3 — From source

git clone https://github.com/asgard-ai-platform/mcp-ecpay-logistics.git
cd mcp-ecpay-logistics
uv sync
cp .env.example .env
uv run --env-file .env mcp-ecpay-logistics

方式 1 — `uvx`（不安裝，按需執行）

uvx mcp-ecpay-logistics

方式 2 — `pip` / `uv pip`

pip install mcp-ecpay-logistics
# 或
uv pip install mcp-ecpay-logistics

安裝後可直接使用 mcp-ecpay-logistics 指令。

方式 3 — 由原始碼安裝

git clone https://github.com/asgard-ai-platform/mcp-ecpay-logistics.git
cd mcp-ecpay-logistics
uv sync
cp .env.example .env
uv run --env-file .env mcp-ecpay-logistics

UsageUsage

The server speaks MCP over stdio. Add it to your client of choice:

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ecpay-logistics": {
      "command": "uvx",
      "args": ["mcp-ecpay-logistics"],
      "env": {
        "ECPAY_ENV": "stage",
        "ECPAY_MERCHANT_ID": "your_merchant_id",
        "ECPAY_HASH_KEY": "your_hash_key",
        "ECPAY_HASH_IV": "your_hash_iv"
      }
    }
  }
}

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "ecpay-logistics": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "${PWD}",
      "env": {
        "PYTHONPATH": "${PWD}",
        "ECPAY_ENV": "stage",
        "ECPAY_MERCHANT_ID": "your_merchant_id",
        "ECPAY_HASH_KEY": "your_hash_key",
        "ECPAY_HASH_IV": "your_hash_iv"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "ecpay-logistics": {
      "command": "uvx",
      "args": ["mcp-ecpay-logistics"],
      "env": {
        "ECPAY_ENV": "stage",
        "ECPAY_MERCHANT_ID": "your_merchant_id",
        "ECPAY_HASH_KEY": "your_hash_key",
        "ECPAY_HASH_IV": "your_hash_iv"
      }
    }
  }
}

Environment Variables

Variable	Effect
`ECPAY_ENV`	`stage` or `prod`. Controls the legacy logistics base URL.
`ECPAY_MERCHANT_ID`	Merchant ID used in every signed logistics request.
`ECPAY_HASH_KEY`	HashKey used when generating `CheckMacValue`.
`ECPAY_HASH_IV`	HashIV used when generating `CheckMacValue`.

MCP servers are launched by the MCP client, not by your shell — exporting a variable in ~/.zshrc or ~/.bashrc will not reach the server. Put variables in the client config's env block and restart the client after editing.

伺服器透過 stdio 走 MCP 協定，依你的 client 加入設定：

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "ecpay-logistics": {
      "command": "uvx",
      "args": ["mcp-ecpay-logistics"],
      "env": {
        "ECPAY_ENV": "stage",
        "ECPAY_MERCHANT_ID": "your_merchant_id",
        "ECPAY_HASH_KEY": "your_hash_key",
        "ECPAY_HASH_IV": "your_hash_iv"
      }
    }
  }
}

Claude Code

加入專案 .mcp.json：

{
  "mcpServers": {
    "ecpay-logistics": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "${PWD}",
      "env": {
        "PYTHONPATH": "${PWD}",
        "ECPAY_ENV": "stage",
        "ECPAY_MERCHANT_ID": "your_merchant_id",
        "ECPAY_HASH_KEY": "your_hash_key",
        "ECPAY_HASH_IV": "your_hash_iv"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json：

{
  "mcpServers": {
    "ecpay-logistics": {
      "command": "uvx",
      "args": ["mcp-ecpay-logistics"],
      "env": {
        "ECPAY_ENV": "stage",
        "ECPAY_MERCHANT_ID": "your_merchant_id",
        "ECPAY_HASH_KEY": "your_hash_key",
        "ECPAY_HASH_IV": "your_hash_iv"
      }
    }
  }
}

環境變數

變數	效果
`ECPAY_ENV`	`stage` 或 `prod`，控制物流舊制 base URL。
`ECPAY_MERCHANT_ID`	每次已簽名物流 request 都會使用的 MerchantID。
`ECPAY_HASH_KEY`	用來產生 `CheckMacValue` 的 HashKey。
`ECPAY_HASH_IV`	用來產生 `CheckMacValue` 的 HashIV。

MCP server 是由 client 啟動的，不是從你的 shell 啟動；在 ~/.zshrc 或 ~/.bashrc export 的變數不會自動進到 server。請把變數放進 client config 的 env 區塊，改完後重啟 client。

Example Tool UsageExample Tool Usage

You: Create a CVS logistics order in staging.

AI call: ecpay-logistics - create_logistics_order (MCP)(payload: {"MerchantTradeNo": "LOG202605040001", "MerchantTradeDate": "2026/05/04 12:00:00", "LogisticsType": "CVS", "LogisticsSubType": "UNIMARTC2C", "GoodsAmount": 100, "GoodsName": "Demo Item", "SenderName": "Alice", "SenderCellPhone": "0912345678", "ReceiverName": "Bob", "ReceiverCellPhone": "0987654321", "ReceiverStoreID": "131386", "ServerReplyURL": "https://example.com/ecpay/callback"})

{
  "ok": true,
  "endpoint": "create_logistics_order",
  "rtn_code": "1",
  "rtn_msg": "OK",
  "allpay_logistics_id": "1234567",
  "merchant_trade_no": "LOG202605040001",
  "data": {
    "RtnCode": "1",
    "RtnMsg": "OK"
  }
}

Result: The order was accepted by ECPay logistics and returned an AllPayLogisticsID.

You: Query that logistics order later.

AI call: ecpay-logistics - query_logistics_order (MCP)(merchant_trade_no: "LOG202605040001", timestamp: 1714824000)

{
  "ok": true,
  "endpoint": "query_logistics_order",
  "logistics_status": "300",
  "allpay_logistics_id": "1234567",
  "merchant_trade_no": "LOG202605040001",
  "shipment_no": "ABC123456789",
  "data": {
    "LogisticsStatus": "300"
  }
}

Result: The tool returned the current parsed ECPay logistics status and key shipment identifiers.

You: Cancel a C2C order.

AI call: ecpay-logistics - cancel_logistics_order (MCP)(allpay_logistics_id: "1234567", cvs_payment_no: "CVS123", cvs_validation_no: "VAL456")

{
  "ok": true,
  "endpoint": "cancel_logistics_order",
  "result": "1|OK",
  "allpay_logistics_id": "1234567"
}

Result: ECPay confirmed the cancel request for the C2C logistics order.

You: Create a CVS logistics order in staging.

{
  "ok": true,
  "endpoint": "create_logistics_order",
  "rtn_code": "1",
  "rtn_msg": "OK",
  "allpay_logistics_id": "1234567",
  "merchant_trade_no": "LOG202605040001",
  "data": {
    "RtnCode": "1",
    "RtnMsg": "OK"
  }
}

Result: The order was accepted by ECPay logistics and returned an AllPayLogisticsID.

You: Query that logistics order later.

AI call: ecpay-logistics - query_logistics_order (MCP)(merchant_trade_no: "LOG202605040001", timestamp: 1714824000)

{
  "ok": true,
  "endpoint": "query_logistics_order",
  "logistics_status": "300",
  "allpay_logistics_id": "1234567",
  "merchant_trade_no": "LOG202605040001",
  "shipment_no": "ABC123456789",
  "data": {
    "LogisticsStatus": "300"
  }
}

Result: The tool returned the current parsed ECPay logistics status and key shipment identifiers.

You: Cancel a C2C order.

AI call: ecpay-logistics - cancel_logistics_order (MCP)(allpay_logistics_id: "1234567", cvs_payment_no: "CVS123", cvs_validation_no: "VAL456")

{
  "ok": true,
  "endpoint": "cancel_logistics_order",
  "result": "1|OK",
  "allpay_logistics_id": "1234567"
}

Result: ECPay confirmed the cancel request for the C2C logistics order.

Project StructureProject Structure

mcp-ecpay-logistics/
├── app.py                             # FastMCP singleton
├── mcp_server.py                      # Entry point (stdio transport)
├── config/settings.py                 # ECPay environment and endpoint selection
├── connectors/ecpay_logistics_client.py # Legacy signing, POST, and response parsing
├── tools/logistics_tools.py           # create/query/cancel tools
├── scripts/auth/test_connection.py
└── tests/
    └── test_all_tools.py

mcp-ecpay-logistics/
├── app.py                               # FastMCP 單例
├── mcp_server.py                        # 入口（stdio 傳輸）
├── config/settings.py                   # 綠界環境與 endpoint 選擇
├── connectors/ecpay_logistics_client.py # 舊制簽名、POST、response parsing
├── tools/logistics_tools.py             # create / query / cancel tools
├── scripts/auth/test_connection.py
└── tests/
    └── test_all_tools.py

Ecpay Logistics Notes DisclaimerEcpay Logistics Notes Disclaimer

This project targets ECPay's legacy logistics APIs. These are merchant-authenticated form endpoints, not public anonymous APIs.

Please note: Required fields vary by LogisticsType / LogisticsSubType. For example, CVS flows need ReceiverStoreID, and several C2C flows require sender / receiver cell-phone fields. Treat the payload examples in this README as integration illustrations, not a universal schema for every ECPay logistics product.

The server follows ECPay's legacy CheckMacValue flow (sort parameters, wrap with HashKey / HashIV, URL-encode, MD5, uppercase). If your request is rejected, verify the environment, merchant keys, and exact payload fields first.

This project targets ECPay's legacy logistics APIs. These are merchant-authenticated form endpoints, not public anonymous APIs.

Please note: Required fields vary by LogisticsType / LogisticsSubType. For example, CVS flows need ReceiverStoreID, and several C2C flows require sender / receiver cell-phone fields. Treat the payload examples in this README as integration illustrations, not a universal schema for every ECPay logistics product.

綠界物流整合注意事項與聲明綠界物流整合注意事項與聲明

本專案對接的是 綠界物流舊制 API。這些是 merchant-authenticated 的 form endpoint，不是公開匿名 API。

請注意： 必填欄位會依 LogisticsType / LogisticsSubType 改變。像 CVS 流程需要 ReceiverStoreID，而數個 C2C 流程還需要 sender / receiver 手機欄位。README 裡的 payload 範例是整合示意，不是所有物流產品都通用的 schema。

本 server 採用綠界舊制 CheckMacValue 規則（排序參數、包 HashKey / HashIV、URL encode、MD5、轉大寫）。若請求被拒，請先檢查環境、商店金鑰與 payload 欄位是否完全正確。

本專案對接的是 綠界物流舊制 API。這些是 merchant-authenticated 的 form endpoint，不是公開匿名 API。

請注意： 必填欄位會依 LogisticsType / LogisticsSubType 改變。像 CVS 流程需要 ReceiverStoreID，而數個 C2C 流程還需要 sender / receiver 手機欄位。README 裡的 payload 範例是整合示意，不是所有物流產品都通用的 schema。

Tags標籤

logisticsecpayconvenience-storetaiwan

Related MCP Servers相關 MCP 伺服器

Released已發布

Shopline Shopline 電商平台

MCP Server for Shopline e-commerce platform — 143 AI-callable tools (75 read + 68 write) covering or...

Shopline 電商平台 MCP Server — 143 個 AI 可呼叫工具（75 讀 + 68 寫），涵蓋訂單、商品、庫存、顧客、促銷等。

ecommerceshoplinetaiwan

ecommerce taiwan 143 tools工具 by @asgard-ai-platform

Coming Soon即將推出

7-Eleven Pickup 7-Eleven 超商取貨

MCP Server for 7-Eleven store pickup service, enabling store selection, shipment creation, and picku...

7-Eleven 超商取貨 MCP Server，支援透過 AI 代理進行門市選擇、出貨建立與取貨追蹤。

logisticsconvenience-storetaiwan

ecommerce taiwan by @asgard-ai-platform

Coming Soon即將推出

91APP 91APP 全通路零售

MCP Server for 91APP omni-channel retail platform, providing unified online and offline commerce cap...

91APP 全通路零售平台 MCP Server，為 AI 代理提供線上線下整合的商務功能。

ecommerceomnichanneltaiwan

ecommerce taiwan by @asgard-ai-platform

ECPay Logistics 綠界物流

Features功能特色

Available Tools可用工具

Development開發

License授權

RequirementsRequirements

InstallInstall

Option 1 — uvx (no install, runs on demand)

Option 2 — pip / uv pip

Option 3 — From source

方式 1 — uvx（不安裝，按需執行）

方式 2 — pip / uv pip

方式 3 — 由原始碼安裝

UsageUsage

Claude Desktop

Claude Code

Cursor

Environment Variables

Claude Desktop

Claude Code

Cursor

環境變數

Example Tool UsageExample Tool Usage

Project StructureProject Structure

Ecpay Logistics Notes DisclaimerEcpay Logistics Notes Disclaimer

綠界物流整合注意事項與聲明綠界物流整合注意事項與聲明

Tags標籤

Related MCP Servers相關 MCP 伺服器

Shopline Shopline 電商平台

7-Eleven Pickup 7-Eleven 超商取貨

91APP 91APP 全通路零售

Option 1 — `uvx` (no install, runs on demand)

Option 2 — `pip` / `uv pip`

方式 1 — `uvx`（不安裝，按需執行）

方式 2 — `pip` / `uv pip`