trackmage

This MCP server exposes the TrackMage shipment tracking API and logistics capabilities through the MCP (Model Context Protocol) interface. It enables creation and management of shipments and orders, retrieval of shipment checkpoints, and carrier detection across TrackMage’s network, with OAuth-based authentication to the TrackMage API. You can interact with the server using the included MCP resources, such as trackmage:///workspaces/{id}, trackmage:///shipments/{id}, trackmage:///orders/{id}, trackmage:///carriers/{id}, and trackmage:///tracking_statuses/{id}, as well as the core tools for creating and updating shipments and orders, listing resources, and retracking shipments.

To use the server, start it with the provided Node entry point and ensure your environment variables are properly set (client credentials and workspace ID). The server will authenticate against TrackMage and expose endpoints via the MCP transport you configure (for example HTTP on localhost:3000). You can then issue MCP requests to perform operations like creating shipments, retrieving checkpoints, listing carriers, and detecting carriers for a given tracking number. The tools and resources mirror TrackMage’s API capabilities, making it straightforward to integrate tracking into your larger workflow or agent-driven processes.

Prerequisites:

• Node.js v18+ installed on your machine
• Access to a TrackMage account with API credentials (Client ID, Client Secret) and a Workspace ID

Installation steps:

1. Clone the MCP server repository:

git clone https://github.com/yourusername/trackmage-mcp-server.git
cd trackmage-mcp-server

2. Install dependencies:

npm install

3. Create and configure environment variables:

cp .env.example .env

4. Populate .env with your TrackMage credentials:

TRACKMAGE_CLIENT_ID=your_client_id_here
TRACKMAGE_CLIENT_SECRET=your_client_secret_here
TRACKMAGE_WORKSPACE_ID=your_workspace_id_here

5. Start the MCP server:

npm start

6. (Optional) Run tests if provided:

npm test

If you’re deploying with a container or another process manager, configure the command accordingly (see mcp_config example in the JSON below).

Environment variables required by the server:

• TRACKMAGE_CLIENT_ID: Your TrackMage client/application ID
• TRACKMAGE_CLIENT_SECRET: Your TrackMage client secret
• TRACKMAGE_WORKSPACE_ID: The workspace you want to operate within

Common issues:

• Incorrect credentials or workspace ID will cause authentication failures; re-check values in TrackMage Settings > API KEYS and the workspace URL
• Ensure the port used by the MCP transport (e.g., HTTP on 3000) is accessible from your tooling
• If using a reverse proxy, configure proper CORS and network rules
• For sensitive data handling, follow privacy best practices outlined in the README and your organization’s policy

Configuration tips:

• You can configure additional MCP resources and tools in your client calls as shown in the README (shipments, orders, carriers, etc.)
• The server supports both direct MCP file-based configuration and environment-based startup; choose the method that fits your deployment workflow