renfield-mcp-tracking

Multi-carrier parcel-tracking MCP server for Renfield. Talks directly to carrier APIs — no third-party aggregator (no Shippo, AfterShip, EasyPost, …). Your tracking data never passes through a SaaS middleman.

Carriers

Carrier	Backend	Notes
DHL / Deutsche Post	Shipment Tracking – Unified API	Free, production key. One endpoint covers DHL Paket, Express, Deutsche Post, Freight. Initial quota 250 calls/day.
UPS	OAuth client-credentials + Track API	Free developer app.
FedEx	OAuth client-credentials + Track API	Free developer app.
DPD	Web deep-link only	No free public API for private users → returns a link into `tracking.dpd.de`.
Hermes	Web deep-link only	→ `myhermes.de`.
GLS	Web deep-link only	→ `gls-group.com`.

Each API adapter self-disables when its credentials are absent — the server still starts, and list_carriers() reports which carriers are usable. The link-only carriers always work (they only return a tracking URL). Adding real API access for DPD/Hermes/GLS later means dropping in a CarrierAdapter subclass and registering it — no other code changes.

Tools

track_parcel(tracking_number, carrier="auto") — primary. Returns a normalized result: status, status_description, estimated_delivery, events (newest first), web_url, success.
list_carriers() — supported carriers + configured state.
detect_carrier(tracking_number) — guess the carrier from the number format (confident for UPS 1Z… and DHL JJD…; ambiguous numeric numbers fall back to TRACKING_DEFAULT_CARRIER).

Normalized status values

pre_transit · transit · out_for_delivery · delivered · exception · unknown · not_found · link_only · not_configured · error

Configuration

Env var	Purpose
`DHL_API_KEY`	DHL Developer Portal app key (the `DHL-API-Key`).
`UPS_CLIENT_ID` / `UPS_CLIENT_SECRET`	UPS developer app credentials.
`FEDEX_CLIENT_ID` / `FEDEX_CLIENT_SECRET`	FedEx developer app credentials.
`TRACKING_DEFAULT_CARRIER`	Fallback when auto-detect is inconclusive (default `dhl`).
`DHL_TRACKING_BASE_URL` / `UPS_TRACKING_BASE_URL` / `FEDEX_TRACKING_BASE_URL`	Override API base (test environments).

Getting keys

DHL — register at https://developer.dhl.com/, create an app, subscribe it to Shipment Tracking – Unified, copy the key. Works against production.
UPS — https://developer.ups.com/ → create an app → OAuth client id/secret.
FedEx — https://developer.fedex.com/ → create an app → Track API.

Run

pip install -e ".[dev]"
python -m renfield_mcp_tracking      # stdio MCP server
pytest -q

Use in Renfield

Installed into the backend image via src/backend/requirements.txt and run as a stdio server from config/mcp_servers.yaml (name: tracking). Enable with TRACKING_ENABLED=true and set whichever carrier keys you have. Tools become available to the agent as mcp.tracking.track_parcel etc.

License

MIT