list_shipments
Retrieve and filter shipment data from ShipStation with options for pagination, date ranges, recipient names, and order IDs.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "list_shipments"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| pageSize | No | Number of shipments per page (max 500) | |
| sortBy | No | Sort shipments by a specific field | |
| sortDir | No | Sort direction | |
| recipientName | No | Filter by recipient name | |
| createDateStart | No | Filter by creation date (start) | |
| createDateEnd | No | Filter by creation date (end) | |
| shipDateStart | No | Filter by ship date (start) | |
| shipDateEnd | No | Filter by ship date (end) | |
| orderId | No | Filter by order ID |
Implementation Reference
- src/tools/shipment-tools.js:20-32 (handler)The main handler function for the 'list_shipments' tool, which calls the ShipStation API client to fetch shipments and returns formatted JSON response or error.
handler: async (params) => { try { const shipments = await shipStationClient.getShipments(params); return { content: [{ type: "text", text: JSON.stringify(shipments, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: error.message }], isError: true }; } } - src/tools/shipment-tools.js:8-19 (schema)Zod-based input schema defining optional parameters for pagination, sorting, and filtering shipments.
schema: { page: z.number().optional().describe("Page number"), pageSize: z.number().optional().describe("Number of shipments per page (max 500)"), sortBy: z.string().optional().describe("Sort shipments by a specific field"), sortDir: z.enum(["ASC", "DESC"]).optional().describe("Sort direction"), recipientName: z.string().optional().describe("Filter by recipient name"), createDateStart: z.string().optional().describe("Filter by creation date (start)"), createDateEnd: z.string().optional().describe("Filter by creation date (end)"), shipDateStart: z.string().optional().describe("Filter by ship date (start)"), shipDateEnd: z.string().optional().describe("Filter by ship date (end)"), orderId: z.number().optional().describe("Filter by order ID") }, - src/server.js:174-191 (registration)Registration code that iterates over all tool arrays (including shipmentTools containing 'list_shipments') and registers each tool with the MCP server using server.tool().
[ ...orderTools, ...shipmentTools, ...carrierTools, ...warehouseTools, ...productTools, ...customerTools, ...storeTools, ...webhookTools, ...fulfillmentTools ].forEach(tool => { server.tool( tool.name, tool.schema, tool.handler, { description: tool.description } ); }); - src/api-client.js:85-87 (helper)Supporting method in ShipStationClient that makes the actual GET request to /shipments endpoint with parameters.
async getShipments(params) { return this.request('GET', '/shipments', null, params); }