PostEx MCP Server
About
MCP server providing tools to interact with the PostEx Merchant API for order management, tracking, and other logistics operations.
Details
- Author
- faizan45640
- GitHub stars
- 2
- Downloads
- 315
- Categories
- Other
Jump to
- Exposes 14 tools covering order, address, and tracking operations.
- Validates input parameters using Zod schemas.
- Securely passes API token via command line.
- Graceful shutdown on SIGINT and SIGTERM signals.
- Uses node-fetch for HTTP requests to PostEx API.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
PostEx MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install dependencies (@modelcontextprotocol/sdk, zod, node-fetch@2), then run the server with Node.js, passing your PostEx API token as a command-line argument: node index.js <YOUR_POSTEX_API_TOKEN>. The server connects via standard I/O and listens for MCP requests.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"postex mcp server": {
"PostEx-MCP-Server": {
"command": "node",
"args": [
"index.js",
"<YOUR_POSTEX_API_TOKEN>"
]
}
}
}
}McpServers
{
"PostEx-MCP-Server": {
"command": "node",
"args": [
"index.js",
"<YOUR_POSTEX_API_TOKEN>"
]
}
}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
Node.js (LTS version recommended)
npm or yarn
A valid PostEx Merchant API Token
Setup
1. Clone the repository (if applicable) or ensure you have the index.js file.
2. 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
3. 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-fetch for making HTTP requests to the PostEx API.
zod is used for input validation for the tool parameters.
The API token is passed securely as a command-line argument and used in the Authorization header for API calls.
Error handling is basic; check console output for potential issues during API calls.
Graceful shutdown is handled for SIGINT and SIGTERM signals.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
