TrackingMCP Examples

Shipping status is external world state. Your agent can reason about it.

TrackingMCP exposes live container tracking, vessel position, demurrage risk, port congestion, and shipment summaries over a remote MCP server:

https://mcp.trackingmcp.com/mcp

Use this repo to connect Claude Desktop, Claude web/custom connectors, Cursor, Windsurf, VS Code, Cline, curl, Node, or Python in a few minutes.

1. Try the public sandbox key

No card, no sales call, no signup:

export TRACKINGMCP_API_KEY="tmcp_demo_public"

The public key returns synthetic demo shipments only. It is rate-limited to protect the service.

2. Get a live API key

Create a free account, then open Settings -> API Keys:

https://app.trackingmcp.com/settings?tab=api

Keep production keys out of Git. For local testing:

export TRACKINGMCP_API_KEY="tm_live_or_sandbox_xxxxxxxxxxxx"

3. Connect an MCP client

Copy one of these config files into your client:

• Claude Desktop: claude_desktop_config.json
• Cursor: .cursor/mcp.json
• Windsurf: windsurf/mcp_config.json
• VS Code: .vscode/mcp.json
• Cline: cline/mcp_settings.json

Replace YOUR_TRACKINGMCP_API_KEY with your key.

4. Build a freight agent in 10 minutes

1. Connect TrackingMCP to your AI client.
2. Ask for a shipment portfolio summary.
3. Drill into a risky container.
4. Ask for the vessel's live AIS position.
5. Ask the agent to explain the operational risk in plain English.

Try:

Which containers are at demurrage risk this week?

Then:

For the highest-risk container, show the route, ETA confidence, vessel position, and projected demurrage cost.

Five prompts to try

Which containers are at demurrage risk this week?
Summarize all delayed shipments by customer.
Where is vessel IMO 9463297 right now?
Which shipments will miss ETA?
Add this B/L MAEU123456789 and tell me when the first update arrives.

Raw HTTP

List MCP tools:

./curl/list-tools.sh

Call a shipment summary:

./curl/shipment-summary.sh demurrage_risk

Node

cd node
npm install
TRACKINGMCP_API_KEY="$TRACKINGMCP_API_KEY" npm start

Python

cd python
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
TRACKINGMCP_API_KEY="$TRACKINGMCP_API_KEY" python freight_agent.py

Available MCP tools

Tool	Use
get_shipment_summary	Portfolio summary, exceptions, arrivals, and demurrage risk
get_container_detail	Full detail for one container or bill of lading
get_vessel_position	Live AIS position by vessel IMO
get_demurrage_report	Free days, daily rates, and projected costs
get_port_congestion	Congestion by UN/LOCODE
add_container	Start tracking a container or bill of lading

Docs

Full copy-paste docs:

https://app.trackingmcp.com/docs/mcp