colleag-mcp-ups

An MCP server for UPS shipping, running against your own UPS account: rate shopping with negotiated prices, live tracking (with an interactive MCP Apps card), and landed-cost estimates for international shipments.

Built by Colleag.ai, a CargoBeacon AB company. Works with any MCP host — Colleag.ai, Claude Desktop, VS Code, or your own client.

Read-only by design (v0.1). This release quotes, tracks and estimates — it never books shipments or spends money. Side-effecting tools (booking, pickup scheduling) will follow once host-side human-in-the-loop confirmation conventions are settled; a host, not a connector, should own the "are you sure?" step for actions that cost money.

Tools

Setup

1. Create an app on developer.ups.com ("I want to integrate UPS technology into my business") and enable the Rating, Tracking and Landed Cost products. This gives you a Client ID and Secret tied to your UPS account.
2. Configure environment variables:

UPS_CLIENT_ID=...          # required
UPS_CLIENT_SECRET=...      # required, secret
UPS_ACCOUNT_NUMBER=...     # required — your 6-character shipper number
UPS_ENVIRONMENT=test       # 'test' (CIE sandbox, default) or 'production'
SHIP_FROM_NAME="Acme AB"   # optional defaults for the quoting origin
SHIP_FROM_ADDRESS="Industrigatan 1"
SHIP_FROM_CITY=Stockholm
SHIP_FROM_POSTAL_CODE="112 46"
SHIP_FROM_COUNTRY=SE
SHIP_FROM_PHONE="+468..."

3. Run:

uv run colleag-mcp-ups            # stdio (default)
MCP_TRANSPORT=streamable-http uv run colleag-mcp-ups   # HTTP

Claude Desktop

{
  "mcpServers": {
    "ups": {
      "command": "uvx",
      "args": ["colleag-mcp-ups"],
      "env": {
        "UPS_CLIENT_ID": "...",
        "UPS_CLIENT_SECRET": "...",
        "UPS_ACCOUNT_NUMBER": "...",
        "UPS_ENVIRONMENT": "test"
      }
    }
  }
}

Try it without credentials

npx @modelcontextprotocol/inspector uv run colleag-mcp-ups lists the tools and the ui://colleag-mcp-ups/tracking-card resource; calls will return a structured configuration error until UPS credentials are set.

Notes

• Access tokens are cached per expires_in (UPS cut lifetimes to 1 h in April 2026 — never hardcode refresh intervals).
• Rate limits are not published by UPS; the server surfaces HTTP 429 as a structured UPS_RATE_LIMITED error for the host to back off on.
• Tracking retention: UPS purges tracking data after ~120 days; keep your own shipment history if you need longer memory.
• The MCP Apps tracking card is rendered by the host in a sandboxed iframe; hosts without the UI extension simply use the JSON tool result.

License

MIT — see LICENSE.