Shipment Tracker

An MCP (Model Context Protocol) server that tracks DB Schenker shipments. Exposes a single track_shipment tool that accepts a DB Schenker reference number and returns structured shipment data including goods details, tracking history, and per-package events.

Implementations

This repository contains two implementations. The main branch (this one) uses Playwright. An alternative implementation using direct HTTP with a proof-of-work CAPTCHA solver is available on the captcha-pow-direct-http branch.

Playwright (this branch)

The DB Schenker tracking site protects its internal API with a CAPTCHA token generated by browser-side JavaScript. Direct HTTP calls are rejected with 429. To work around this, the server uses Playwright to launch a headless Chromium browser, navigates to the tracking page (letting the browser handle the CAPTCHA automatically), and intercepts the two underlying API responses directly - no HTML scraping involved.

Direct HTTP with proof-of-work solver (captcha-pow-direct-http branch)

The captcha-pow-direct-http branch eliminates the browser dependency entirely. When the API returns 429, the response includes a Captcha-Puzzle header containing proof-of-work challenges. The server solves these using a double SHA-256 loop (reverse-engineered from the site's JS), then retries the request with a Captcha-Solution header. This approach has no Playwright overhead and scales to concurrent calls trivially, but is more fragile to site changes since it depends on a reverse-engineered algorithm.

Prerequisites

• .NET 9 SDK
• Playwright's Chromium browser (one-time install, see below)

Setup

1. Clone the repository

git clone <repo-url>
cd shipment-tracker-mcp-server

2. Install Chromium for Playwright

dotnet build --configuration Release src/ShipmentTrackerMcp
dotnet tool install --global Microsoft.Playwright.CLI
playwright install chromium

Connecting to an MCP client

This server implements the standard MCP protocol and works with any MCP-compatible client. Below is an example configuration for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "shipment-tracker": {
      "command": "dotnet",
      "args": [
        "run",
        "--no-build",
        "--configuration", "Release",
        "--project", "C:\\path\\to\\shipment-tracker-mcp-server\\src\\ShipmentTrackerMcp"
      ]
    }
  }
}

Replace C:\\path\\to\\ with the actual path on your machine. Note that backslashes must be doubled in JSON.

After updating the config, restart Claude Desktop. You can then ask Claude to track a shipment:

"Track DB Schenker shipment 1806290829"

Testing with real shipments

Once connected to an MCP client, try reference number 1806290829.

To test error handling, use an invalid reference such as 0000000000 - the tool should return a "not found" error rather than timing out.

Running the tests

dotnet test

Known limitations

• No sender/receiver names - the API returns location data only (city, postcode, country). Names are not available.
• Latency - each call launches a new headless browser instance (~2-3s overhead) to let the browser handle the CAPTCHA. A production version would maintain a persistent browser session.
• stdio transport - the server runs as a local process on the host machine. A production version would use HTTP-based transport, allowing it to be deployed as a shared service and accessed by multiple clients without local installation.