Terminal49 MCP Server

Use the Terminal49 MCP server to let Claude or Cursor answer questions with live container and shipment data—without writing custom glue code.

TL;DR – Get Started in 5 Minutes

Get your API token

Go to the Terminal49 dashboard → Settings → API Tokens and create a T49_API_TOKEN.

Pick your MCP client

Claude Desktop (macOS / Windows / Linux)
Cursor IDE

Paste this config (Claude Desktop)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "terminal49": {
      "url": "https://mcp.terminal49.com/mcp",
      "headers": {
        "Authorization": "Bearer <T49_API_TOKEN>"
      }
    }
  }
}

Cursor IDE config

{
  "mcp": {
    "servers": {
      "terminal49": {
        "url": "https://mcp.terminal49.com/mcp",
        "headers": {
          "Authorization": "Bearer <T49_API_TOKEN>"
        }
      }
    }
  }
}

Ask Claude

“Using the Terminal49 MCP server, track container CAIU1234567 with Maersk.”

Explore tools

Ask Claude:

“List the tools available in the Terminal49 MCP server and what they’re for.”

Need test container numbers? See Test Numbers for containers you can use during development.

For the full walkthrough (including local stdio dev, deployment, and SDK examples), see MCP Server Quickstart.

Transports

Transport	Endpoint	Best For
HTTP (streamable)	`POST /api/mcp` or `POST /mcp`	Serverless, short-lived requests

Authentication:

API token only (OAuth not required for this release)
Header: Authorization: Bearer <T49_API_TOKEN> or Authorization: Token <T49_API_TOKEN>
Or set T49_API_TOKEN environment variable when self-hosting

Claude Desktop and Cursor use the HTTP transport at https://mcp.terminal49.com/mcp.

Planning OAuth for hosted MCP? Use the Hosted HTTP OAuth Requirements and Hosted HTTP OAuth Test Plan.

The same rate limits apply to MCP endpoints as the REST API.

Tools Reference

`search_container`

Find containers by container number, BL, booking, or your own reference. This is the fastest way to locate containers. Parameters

query (string, required) – container number, BL, booking, or reference

Example MCP request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_container",
    "arguments": {
      "query": "CAIU1234567"
    }
  }
}

Example response

{
  "containers": [
    {
      "id": "abc-123-uuid",
      "containerNumber": "CAIU1234567",
      "status": "in_transit",
      "shippingLine": "Maersk",
      "podTerminal": "APM Terminals",
      "destination": "Los Angeles"
    }
  ],
  "shipments": [],
  "totalResults": 1
}

Good for

“Find this container and tell me where it is”
“Show all containers with reference PO-12345”

REST equivalent: GET /containers with filters

`track_container`

Start tracking a new container. Creates a tracking request and returns container details. Parameters

number (string, required) – container number, BL, or booking number
numberType (string, optional) – override inference (container, bill_of_lading, booking_number)
scac (string, optional) – shipping line code, e.g., MAEU for Maersk
refNumbers (string[], optional) – your reference numbers

Example MCP request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "track_container",
    "arguments": {
      "number": "CAIU1234567",
      "scac": "MAEU"
    }
  }
}

Good for

“Track container CAIU1234567 with Maersk”
“Start tracking this new shipment”

REST equivalent: POST /tracking_requests

`get_container`

Get detailed container information with flexible data loading. Choose what to include based on your question. Parameters

id (uuid, required) – Terminal49 container UUID
include (string[], optional) – what to load:
- shipment – routing, BOL, line, ref numbers (lightweight)
- pod_terminal – terminal name, location (lightweight)
- transport_events – full event history (heavy, 50-100 events)

Example MCP request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_container",
    "arguments": {
      "id": "abc-123-uuid",
      "include": ["shipment", "pod_terminal"]
    }
  }
}

Example response (mapped)

{
  "id": "abc-123-uuid",
  "number": "CAIU1234567",
  "status": "available_for_pickup",
  "equipment": {
    "type": "40HC",
    "length": "40",
    "height": "high_cube"
  },
  "location": {
    "currentLocation": "APM Terminals",
    "availableForPickup": true,
    "podArrivedAt": "2025-01-15T08:30:00Z",
    "podDischargedAt": "2025-01-16T14:20:00Z"
  },
  "demurrage": {
    "pickupLfd": "2025-01-22",
    "holds": [],
    "fees": []
  },
  "shipment": {
    "id": "shipment-uuid",
    "billOfLading": "MAEU123456789",
    "shippingLineScac": "MAEU"
  }
}

Good for

“What’s the status of this container?”
“Is it available for pickup? Any holds?”
“When does demurrage start?”

REST equivalent: GET /containers/

`get_container_transport_events`

Get the full event timeline for a container’s journey. Parameters

id (uuid, required) – Terminal49 container UUID

Example response

{
  "totalEvents": 47,
  "eventCategories": {
    "vesselEvents": 8,
    "railEvents": 12,
    "terminalEvents": 18
  },
  "milestones": {
    "vesselLoadedAt": "2024-12-08T10:30:00Z",
    "vesselDepartedAt": "2024-12-09T14:00:00Z",
    "vesselArrivedAt": "2024-12-22T08:30:00Z",
    "dischargedAt": "2024-12-23T11:15:00Z"
  },
  "timeline": [
    {
      "event": "container.transport.vessel_loaded",
      "timestamp": "2024-12-08T10:30:00Z",
      "location": { "name": "Shanghai", "locode": "CNSHA" }
    }
  ]
}

Good for

“Show me the journey timeline”
“What happened to this container?”
“How long was the rail portion?”

REST equivalent: GET /containers//transport_events

`get_shipment_details`

Get shipment-level information including routing, BOL, and all containers. Parameters

id (uuid, required) – Terminal49 shipment UUID
include_containers (boolean, optional) – include container list (default: true)

Good for

“Tell me about this shipment”
“What containers are on this BL?”
“Show me the routing”

REST equivalent: GET /shipments/

`get_supported_shipping_lines`

List carriers supported by Terminal49 with their SCAC codes. Parameters

search (string, optional) – filter by name or SCAC

Good for

“What carriers do you support?”
“What’s the SCAC code for CMA CGM?”

REST equivalent: GET /shipping_lines

`get_container_route`

Get detailed multi-leg routing with vessel itinerary.

This is a paid feature. If not enabled for your account, use get_container_transport_events for historical movement data instead.

Parameters

id (uuid, required) – Terminal49 container UUID

Good for

“What’s the routing for this container?”
“Which transshipment ports?”
“What vessel is it on?”

REST equivalent: GET /containers//route

`list_shipments`

List shipments with optional filters and pagination. Parameters

status, port, carrier, updated_after (string, optional)
include_containers (boolean, optional)
page, page_size (number, optional)

Good for

“List recent shipments”
“Show in-transit shipments for MAEU”

REST equivalent: GET /shipments

`list_containers`

List containers with optional filters and pagination. Parameters

status, port, carrier, updated_after (string, optional)
include (string, optional) – comma-separated include list
page, page_size (number, optional)

Good for

“List containers updated in the last 24h”
“Show containers at a specific POD port”

REST equivalent: GET /containers

`list_tracking_requests`

List tracking requests with optional filters and pagination. Parameters

filters (object, optional) – raw query filters
page, page_size (number, optional)

Good for

“Show failed tracking requests”
“List latest tracking activity”

REST equivalent: GET /tracking_requests

Prompts Reference

Prompts are pre-built workflows that guide the AI through multi-step analysis.

`track-shipment`

Quick container tracking with optional carrier specification. Arguments

container_number (string, required) – e.g., CAIU1234567
carrier (string, optional) – SCAC code, e.g., MAEU

Try this in Claude:

“Using Terminal49, track container CAIU1234567 and show me its current status, location, and ETA.”

`check-demurrage`

Analyze demurrage/detention risk for a container. Arguments

container_id (uuid, required) – from search_container or get_container

Try this in Claude:

“Using Terminal49, check demurrage risk for container CAIU1234567 and explain which fees apply and when.”

`analyze-delays`

Identify delays and root causes in a container’s journey. Arguments

container_id (uuid, required) – Container UUID

Try this in Claude:

“Using Terminal49, analyze delays for container CAIU1234567 and tell me what caused them.”

Resources Reference

Resources provide static or dynamic data that AI clients can read.

Resource URI	Description
`terminal49://container/{id}`	Container data in markdown format
`terminal49://docs/milestone-glossary`	Event/milestone reference documentation

Example resources/read request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": {
    "uri": "terminal49://docs/milestone-glossary"
  }
}

Not Yet Supported

These Terminal49 API capabilities are available via the SDK but not yet exposed as MCP tools:

API	Description	Workaround
`update_shipment`	Update shipment ref numbers/tags	Use REST API
`stop_tracking`	Stop tracking a shipment	Use REST API
`resume_tracking`	Resume tracking a shipment	Use REST API
`raw_events`	Get raw EDI event data	Use REST API
`refresh_container`	Force refresh container data	Use REST API
Webhooks	Real-time event notifications	Configure via dashboard

Shipment/container list operations are available via MCP. Update/stop/resume tracking operations still require REST API or direct SDK usage.

MCP Server Quickstart – Full setup, local dev, deployment
Rate Limiting – Same limits apply to MCP
Test Numbers – Containers for testing
Webhooks – Real-time updates (use with MCP for best results)

MCP

​Terminal49 MCP Server

​TL;DR – Get Started in 5 Minutes

​Transports

​Tools Reference

​search_container

​track_container

​get_container

​get_container_transport_events

​get_shipment_details

​get_supported_shipping_lines

​get_container_route

​list_shipments

​list_containers

​list_tracking_requests

​Prompts Reference

​track-shipment

​check-demurrage

​analyze-delays

​Resources Reference

​Not Yet Supported

​Related Guides

Terminal49 MCP Server

TL;DR – Get Started in 5 Minutes

Transports

Tools Reference

`search_container`

`track_container`

`get_container`

`get_container_transport_events`

`get_shipment_details`

`get_supported_shipping_lines`

`get_container_route`

`list_shipments`

`list_containers`

`list_tracking_requests`

Prompts Reference

`track-shipment`

`check-demurrage`

`analyze-delays`

Resources Reference

Not Yet Supported

Related Guides