Integrieren Sie den DHL API Assistant MCP Server in Ihre KI-Umgebung, um über natürliche Sprache und strukturierte Tool-Aufrufe auf DHL Versand-, Retouren-, Label- und Tracking-Funktionen zuzugreifen.

Einführung

Die Integration von DHL Post & Paket Deutschland APIs kann komplex sein. Unterschiedliche Endpunkte, Authentifizierungsmethoden und Datenformate erhöhen den Implementierungsaufwand und verlangsamen die Umsetzung.

Der DHL API Assistant MCP Server vereinfacht dies, indem er eine zentrale technische Verbindung zwischen Ihrer KI-Umgebung und den DHL APIs bereitstellt. Er stellt DHL-Funktionen über das Model Context Protocol (MCP) als KI-kompatible Tools bereit und liefert den benötigten Integrationskontext direkt dort, wo Sie arbeiten.

Das bedeutet, dass KI-Systeme wie IDE-Assistenten, Chat-Agenten und Automatisierungstools die Entwicklung und den Betrieb einer DHL-API-Anbindung unterstützen können, zum Beispiel bei:

  • Code Completion für Requests und zugehörige Integrationslogik
  • agentengestützter Umsetzung der API-Anbindung
  • Fehleranalyse und Debugging während der Integration
  • Erstellung und Auswertung von Testfällen

In agentenfähigen Umgebungen kann der MCP Server direkt aus demselben Workspace angesprochen werden, in dem Sie Ihre Integration entwickeln, testen und verfeinern.

Unterstützte APIs

Der MCP Server unterstützt derzeit die Integration mit den folgenden APIs:

Tipp: Damit Ihre KI-Umgebung den MCP Server im beabsichtigten API-Kontext verwendet, empfiehlt es sich, die relevante DHL API im Prompt oder in der Aufgabenbeschreibung ausdrücklich zu nennen. Beispiel: Fragen Sie nicht nur nach „Erstelle einen Shipment Request“, sondern nennen Sie „DHL Parcel DE Private Shipping“, wenn dies die API ist, mit der Sie arbeiten möchten.

Authentifizierung

Erforderlich

Alle Requests an den MCP Server müssen einen gültigen API Key enthalten:

Header Beschreibung
dhl-api-key API Key für den MCP-Zugriff

Der für den MCP Server verwendete dhl-api-key ist identisch mit dem API Key, der auch für die unterstützten DHL APIs verwendet wird. Sie erhalten diesen Key, wenn Sie im DHL Developer Portal eine App erstellen.

Optional

Abhängig von der verwendeten API können zusätzliche Header erforderlich sein:

Header Beschreibung
dhl-api-secret API-Authentifizierung, falls erforderlich
dhl-username DHL Benutzer-Authentifizierung
dhl-password DHL Benutzerpasswort

Um eine Verbindung herzustellen, ist nur der dhl-api-key erforderlich.
Ob dhl-api-secret, dhl-username und dhl-password benötigt werden, hängt von der jeweiligen API ab. Details zur für die DHL Sandbox erforderlichen Authentifizierung finden Sie in der Dokumentation der jeweiligen API aus dem Abschnitt zu den unterstützten APIs.

Endpoint

Sandbox-Umgebung:

https://api-sandbox.dhl.com/development/mcp/v1/

Wichtig: Der MCP Server und die dafür benötigten Credentials sind ausschließlich für die Sandbox-Umgebung gültig. Der MCP Server bietet keinen Zugriff auf Produktionsumgebungen. Wenn Sie später von der Sandbox in die Produktion wechseln, muss diese Umstellung manuell durch den Entwickler vorgenommen werden. Dazu gehören sowohl die Anpassung der Ziel-URL der API als auch die Verwendung der für die Produktionsumgebung gültigen Credentials.

Diese Anleitung beschreibt, wie ein KI-Client mit dem DHL MCP Server in der Sandbox-Umgebung verbunden wird. API-spezifische Business-Flows, das Verhalten einzelner Endpunkte und zusätzliche Authentifizierung außerhalb des MCP Servers müssen der Dokumentation der jeweiligen unterstützten API entnommen werden. Beispiel: Wenn eine API eine Frontend-URL wie entryUrl zurückliefert, gehören die Zugriffsvoraussetzungen für dieses Frontend nicht zur Authentifizierung des MCP Servers.

Integration

Der DHL MCP Server kann in unterschiedliche Umgebungen integriert werden.
Die folgenden Beispiele zeigen gängige clientseitige Konfigurationen für denselben Sandbox-Endpoint.

VS Code / Cursor / Windsurf

{
  "servers": {
    "DHL API Assistant": {
      "url": "https://api-sandbox.dhl.com/development/mcp/v1/",
      "headers": {
        "dhl-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Beispiel mit allen unterstützten Headern, falls von der verwendeten API erforderlich:

{
  "servers": {
    "DHL API Assistant": {
      "url": "https://api-sandbox.dhl.com/development/mcp/v1/",
      "headers": {
        "dhl-api-key": "YOUR_API_KEY",
        "dhl-api-secret": "YOUR_API_SECRET",
        "dhl-username": "YOUR_USERNAME",
        "dhl-password": "YOUR_PASSWORD"
      }
    }
  }
}

Sehen Sie hier mehr Informationen für die Verwendung von Visual Studio Code.

Codex (CLI / IDE)

Bearbeiten Sie:

~/.codex/config.toml
[mcp_servers.dhl_api_assistant]
url = "https://api-sandbox.dhl.com/development/mcp/v1/"

[mcp_servers.dhl_api_assistant.http_headers]
dhl-api-key = "YOUR_API_KEY"

OpenAI API (Responses API)

const response = await client.responses.create({
  model: "gpt-4.1",
  tools: [
    {
      type: "mcp",
      server_url: "https://api-sandbox.dhl.com/development/mcp/v1/",
      headers: {
        "dhl-api-key": "YOUR_API_KEY",
      },
    },
  ],
  input:
    "Erstelle über die Parcel DE Shipping API ein Versandlabel. Nutze Testdaten",
});

Claude Desktop

{
  "mcpServers": {
    "dhl-api-assistant": {
      "url": "https://api-sandbox.dhl.com/development/mcp/v1/",
      "headers": {
        "dhl-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Validierung

Nach der Konfiguration:

  • Stellen Sie sicher, dass der MCP Server erreichbar ist
  • Prüfen Sie, ob Tools in Ihrer KI-Umgebung verfügbar sind
  • Testen Sie mit einem einfachen Prompt, zum Beispiel:
Bitte prüfe den Status für die DHL-Sendungsnummer 003404341234567890

Fehlerbehebung

MCP Server nicht verfügbar

  • Prüfen Sie, ob dhl-api-key korrekt gesetzt ist
  • Prüfen Sie die Endpoint-URL
  • Stellen Sie sicher, dass Netzwerkzugriff besteht

Tools nicht sichtbar

  • Die Authentifizierung ist möglicherweise unvollständig
  • Zusätzliche Header können erforderlich sein

Autorisierungsfehler (401/403)

  • Ungültiger API Key
  • Fehlende oder falsche Credentials

Best Practices für Sicherheit

  • Speichern Sie keine Credentials im Quellcode
  • Verwenden Sie Umgebungsvariablen oder Secret-Manager
  • Trennen Sie Sandbox- und Produktions-Credentials

Wichtigste Punkte

  • Für die Verbindung mit dem DHL MCP Server ist nur ein gültiger API Key erforderlich
  • Zusätzliche Header sind optional und ermöglichen erweiterte Funktionen
  • Dieselbe Konfiguration kann auf mehrere KI-Umgebungen angepasst werden

Support

Technischer Support & Hilfe

Für weiterführende Unterstützung besuchen Sie bitte unser IT-Portal. Dort können Sie ein Ticket eröffnen und erhalten direkte Hilfe vom DHL-Support. Bitte schildern Sie Ihre Anfrage möglichst detailliert und fügen Sie nachvollziehbare Auszüge der Webservice-Kommunikation bei. So können wir Ihnen schnell und gezielt weiterhelfen.

Customer Integration Services (CIS)

Geschäftszeiten: Mo - Fr von 8:00 - 16:00 Uhr