PostEx-MCP-Server
If you are the rightful owner of PostEx-MCP-Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The PostEx MCP Server is a Model Context Protocol server that interacts with the PostEx Merchant API (v4.1.9) to provide various tools for managing merchant operations.
PostEx MCP Server
This project implements a Model Context Protocol (MCP) server that provides tools for interacting with various endpoints of the PostEx Merchant API (v4.1.9).
Prerequisites
Setup
- Clone the repository (if applicable) or ensure you have the
index.jsfile. - Install dependencies:
npm install @modelcontextprotocol/sdk zod node-fetch@2 # Use v2 for require syntax compatibility # or yarn add @modelcontextprotocol/sdk zod node-fetch@2 - Obtain your PostEx API Token from your PostEx merchant account or representative.
Running the Server
Execute the server using Node.js, providing your PostEx API token as a command-line argument:
node index.js <YOUR_POSTEX_API_TOKEN>
Replace <YOUR_POSTEX_API_TOKEN> with your actual token.
The server will connect via standard I/O and log status messages to standard error. It is now ready to receive MCP requests.
Available Tools
The server exposes the following tools, corresponding to PostEx API endpoints:
getOperationalCities: Get a list of cities where PostEx operates.getMerchantAddress: Get the merchant's registered pickup addresses.createMerchantAddress: Create a new pickup address for the merchant.getOrderTypes: Get the types of orders supported (e.g., "Normal", "Reverse").createOrder: Create a new order in the PostEx system.getUnbookedOrders: List orders created but not yet booked for pickup within a date range.trackOrder: Track a single order using its tracking number.trackBulkOrder: Track multiple orders using a list of tracking numbers. (Note: API docs specify GET but require a body; implementation uses GET as per latest code change, which might not work as expected with a body).saveShipperAdvice: Provide advice (e.g., retry, return) for an attempted parcel.getShipperAdvice: Retrieve shipper advice history for a tracking number.cancelOrder: Cancel an order using its tracking number. (Note: Implemented as PUT with a JSON body).getPaymentStatus: Check the payment settlement status for an order.getOrderStatus: Get a list of all possible order statuses.listOrders: List orders within a date range, optionally filtered by status ID.
Note: Tools corresponding to API endpoints that return PDF files (generate-load-sheet, get-invoice) are not implemented in this version.
Development Notes
- The server uses
node-fetchfor making HTTP requests to the PostEx API. zodis used for input validation for the tool parameters.- The API token is passed securely as a command-line argument and used in the
Authorizationheader for API calls. - Error handling is basic; check console output for potential issues during API calls.
- Graceful shutdown is handled for
SIGINTandSIGTERMsignals.
