Trackmage MCP Server

1# TrackMage MCP Server - Shipment Tracking API & Logistics API Integration
2 
3A Model Context Protocol (MCP) server for shipment tracking api, package monitoring, and logistics management using the TrackMage API. Supports tracking across 1600+ carriers worldwide.
4 
5## Features
6 
7- **Carrier Support**: Track packages across 1600+ carriers worldwide ([full list](https://trackmage.com/carriers/))
8- **Resources**: Workspaces, shipments, orders, carriers, tracking statuses
9- **Tools**: Create shipments/orders, get shipment checkpoints, carrier detection
10- **Authentication**: OAuth with client credentials
11 
12## ⚠️ Data Privacy Notice
13 
14**Data sharing with your LLM provider**: This MCP server provides data to whichever LLM you're using (Claude, ChatGPT, etc.). While this is the expected behavior for MCP servers, please ensure you're comfortable sharing logistics data including tracking numbers, customer emails, addresses, and shipment details with your chosen LLM provider.
15 
16**Best practices:**
17- Only use with non-sensitive or test data if you have privacy concerns
18- Check your LLM provider's data handling policies
19- Consider opting out of training data programs if available
20- Ensure compliance with your organization's data policies
21 
22## Prerequisites
23 
24- Node.js v18+
25- TrackMage account
26 
27## Getting Credentials
28 
291. Register and log into [TrackMage](https://app.trackmage.com).
302. Go to **Settings > API KEYS**.
313. Enter an **App Name** (e.g., "MCP") and **App URL** (e.g., `http://localhost:3000`).
324. Click **Generate** and copy your **Client ID** and **Client Secret**.
335. Note your **Workspace ID** from the dashboard URL.
34 
35## Installation
36 
37### Option 1: Local Setup
38 
39```bash
40git clone https://github.com/yourusername/trackmage-mcp-server.git
41cd trackmage-mcp-server
42npm install
43cp .env.example .env
44# Edit .env with your credentials
45npm start
46```
47 
48## Configuration
49 
50Edit `.env`:
51 
52```
53TRACKMAGE_CLIENT_ID=your_client_id_here
54TRACKMAGE_CLIENT_SECRET=your_client_secret_here
55TRACKMAGE_WORKSPACE_ID=your_workspace_id_here
56```
57 
58## Usage
59 
60Run the server:
61 
62```bash
63npm start
64```
65and then use
66```
67{
68  "mcpServers": {
69    "trackmage": {
70      "transport": {
71        "type": "http",
72        "host": "localhost",
73        "port": 3000
74      }
75    }
76  }
77}
78 
79```
80or using file process:
81```
82{
83  "mcpServers": {
84 
85    "trackmage": {
86      "command": "node",
87      "args": ["/path/to/trackmage-mcp-server/index.js"],
88      "env": {
89        "TRACKMAGE_CLIENT_ID": "your_client_id_here",
90        "TRACKMAGE_CLIENT_SECRET": "your_client_secret_here",
91        "TRACKMAGE_WORKSPACE_ID": "your_workspace_id_here"
92      }
93    }
94 
95  }
96}
97```
98 
99### MCP Resources
100 
101- `trackmage:///workspaces/{id}`
102- `trackmage:///shipments/{id}`
103- `trackmage:///orders/{id}`
104- `trackmage:///carriers/{id}`
105- `trackmage:///tracking_statuses/{id}`
106 
107### MCP Tools
108 
109#### Shipment Management
110 
111- **`create_shipment`**: Create a new shipment
112  - Parameters: `{ trackingNumber, originCarrier?, email?, workspaceId? }`
113  - Returns: Created shipment object
114 
115- **`update_shipment`**: Update an existing shipment
116  - Parameters: `{ shipmentId, trackingNumber?, originCarrier?, email?, status? }`
117  - Returns: Updated shipment object
118 
119- **`list_shipments`**: List shipments from workspace
120  - Parameters: `{ workspaceId?, page?, itemsPerPage? }`
121  - Returns: Array of shipment objects
122 
123- **`get_shipment_checkpoints`**: Get tracking checkpoints for a shipment
124  - Parameters: `{ shipmentId }`
125  - Returns: Array of tracking checkpoint events
126 
127- **`retrack_shipments`**: Retrack multiple shipments by tracking numbers
128  - Parameters: `{ trackingNumbers: [{ number, originCarrier? }], workspaceId? }`
129  - Returns: Retracking results
130 
131#### Order Management
132 
133- **`create_order`**: Create a new order
134  - Parameters: `{ orderNumber, email?, workspaceId? }`
135  - Returns: Created order object
136 
137- **`update_order`**: Update an existing order
138  - Parameters: `{ orderId, orderNumber?, email?, status? }`
139  - Returns: Updated order object
140 
141- **`list_orders`**: List orders from workspace
142  - Parameters: `{ workspaceId?, page?, itemsPerPage? }`
143  - Returns: Array of order objects
144 
145#### Carrier Management
146 
147- **`list_carriers`**: List available carriers
148  - Parameters: `{ page?, itemsPerPage? }`
149  - Returns: Array of carrier objects with codes and names
150 
151- **`detect_carrier`**: Detect possible carriers for a tracking number
152  - Parameters: `{ trackingNumber }`
153  - Returns: Array of possible carrier matches
154 
155## Testing
156 
157```bash
158npm test
159```
160