royalmail-mcp

Buchen, etikettieren, verfolgen und stornieren Sie Royal Mail- und Parcelforce-Sendungen von jeder MCP-kompatiblen KI wie Claude, Cursor oder Windsurf aus.

Verifiziert mit der Live-Click & Drop-API (April 2026). Buchung, Sendungsverfolgung und Stornierung wurden durchgängig getestet. Der Etikettenabruf wurde gemäß der Spezifikation für OBA-Konten verifiziert.

Funktionsweise

Stellt sechs Tools für jede KI bereit, die MCP unterstützt:

Im Hintergrund kommuniziert es mit https://api.parcel.royalmail.com/api/v1 unter Verwendung Ihres Click & Drop-API-Schlüssels.

Related MCP server: UK Property Intelligence

Beispiel-Prompts

Sobald das MCP in Ihrem KI-Client installiert ist, können Sie Dinge sagen wie:

"Buche einen Brief der 1. Klasse an Alex Taylor, 45 High Street, Manchester M1 1AA, 80 Gramm. Referenz: ORDER-1842."

"Versende diese drei Bestellungen per Tracked 48 und gib mir die orderIdentifiers." (fügen Sie eine Liste von Adressen ein)

"Buche Special Delivery bis 13 Uhr mit 1.000 £ Versicherung an diese Adresse und rufe dann das Etikett ab."

"Storniere Bestellung 1004. Der Kunde hat die falsche Postleitzahl angegeben."

"Was ist der günstigste Einschreibedienst für ein 500g-Paket?" (KI ruft list_services auf und analysiert)

"Verfolge die Bestellungen 1002, 1003 und 1004 und fasse zusammen, wo sich jede befindet."

"Hier sind zehn Bestellungen — buche sie alle über Royal Mail Tracked 24 und gib mir ein PDF, das ich drucken kann." (KI ruft book_batch_and_label auf und gibt den Pfad zum zusammengeführten PDF zurück.)

Die KI übernimmt die Adressanalyse, die Dienstauswahl und die Fehlerbehebung. Sie treffen die geschäftlichen Entscheidungen.

Workflow-Ideen für Unternehmen

Eingebunden in einen KI-Agenten kann dieses MCP echte Versandvorgänge automatisieren:

• Tägliche Auftragsabwicklung. Jeden Morgen liest Ihre KI neue Bestellungen aus Shopify, WooCommerce oder einer Tabelle, bucht jede über Royal Mail mit dem richtigen Dienstleistungsgrad und sendet die Sendungsnummern an den Kunden zurück.

• Kundenservice-Triage. Wenn ein Kunde fragt "Wo ist mein Paket?", ruft Ihre KI track_order auf, fasst den neuesten Status in einfachem Englisch zusammen und entwirft eine Antwort.

• Retourenabwicklung. Ein Kunde beantragt eine Rücksendung. Ihre KI liest die Anfrage, bucht den korrekten Rücksendeservice und sendet das druckbare Etikett direkt zurück, ohne dass Personalaufwand entsteht.

• Multi-Carrier-Kommissionierung. Zusammen mit apc-mcp installiert, vergleicht Ihre KI bei der Buchung Royal Mail und APC und wählt die günstigste oder schnellste Option pro Zielort.

• Großauftragstage. Geben Sie Ihrer KI bei Verkaufsaktionen oder Abo-Box-Versand eine CSV-Datei mit hunderten Bestellungen. Sie bucht alle mit dem richtigen Dienst und der richtigen Versicherungsstufe in einem Durchgang und gibt Ihnen eine Zusammenfassung.

• Checkout-Angebote. Wenn ein Kunde beim Checkout nach Versandkosten fragt, wählt Ihre KI den richtigen Dienst für Gewicht und Postleitzahl, berechnet den Preis und antwortet innerhalb von Sekunden.

Kompatibilität

Funktioniert mit jedem MCP-Client, der stdio-Transport unterstützt:

• Claude Desktop

• Cursor

• Windsurf

• Claude Code

• Zed

ChatGPT, Smithery und andere reine Remote-MCP-Clients benötigen einen HTTP-Transport, der noch nicht enthalten ist. Wenn das für Sie wichtig ist, eröffnen Sie ein Issue, damit ich es priorisieren kann.

Installation

npm install -g royalmail-mcp

Oder führen Sie es ohne Installation aus:

npx royalmail-mcp

Konfiguration

Holen Sie sich Ihren API-Schlüssel unter Click & Drop → Settings → API credentials und setzen Sie dann:

RM_API_KEY=your-royal-mail-api-key
RM_BASE_URL=https://api.parcel.royalmail.com/api/v1

Entweder in einer .env-Datei neben dem Server oder über die Konfiguration Ihres MCP-Clients (siehe unten).

Claude Desktop

Hinzufügen zu ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "royalmail": {
      "command": "npx",
      "args": ["-y", "royalmail-mcp"],
      "env": {
        "RM_API_KEY": "your-royal-mail-api-key"
      }
    }
  }
}

Cursor

Hinzufügen zu ~/.cursor/mcp.json:

{
  "mcpServers": {
    "royalmail": {
      "command": "npx",
      "args": ["-y", "royalmail-mcp"],
      "env": {
        "RM_API_KEY": "your-royal-mail-api-key"
      }
    }
  }
}

Unterstützte Dienste

Plus 22 weitere, einschließlich Varianten mit Unterschrift, Altersverifikationsdiensten und Parcelforce International. Führen Sie list_services für die vollständige Liste aus.

Sie können entweder den benutzerfreundlichen Schlüssel (first-class) oder den Service-Register-Code (OLP1) übergeben. Beides funktioniert. Welche Dienste Ihr Konto nutzen kann, hängt davon ab, was unter Click & Drop → Settings → Shipping services aktiviert ist.

Einschränkungen

Etiketten erfordern ein OBA-Konto

get_label funktioniert nur für Kunden mit einem Royal Mail Online Business Account (OBA), dem Rechnungs-Geschäftskonto. Standard-Pay-as-you-go Click & Drop-Konten erhalten bei get_label den Fehler 403 Forbidden (Feature not available).

Buchung, Sendungsverfolgung und Stornierung funktionieren bei allen Kontotypen. Wenn Sie kein OBA haben, können Sie die Auftragserstellung über dieses MCP automatisieren und die Etiketten dann manuell in der Click & Drop-Benutzeroberfläche drucken.

Registrieren Sie sich für OBA unter auth.parcel.royalmail.com/register/oba.

OBA-Benutzer: "auto-apply-postage" aktivieren

Wenn Sie OBA nutzen, aktivieren Sie zusätzlich "Apply postage automatically on orders imported via API" unter Click & Drop → Settings. Ohne diese Einstellung bleiben Bestellungen Entwürfe und get_label gibt zurück: "Label generation only available for orders with postage applied status".

Sicherheit

Ihr API-Schlüssel gewährt vollen Zugriff auf Ihr Click & Drop-Konto. Behandeln Sie ihn wie ein Passwort.

• Committen Sie niemals .env in Git. Die .gitignore in diesem Repository schließt sie bereits aus.

• Fügen Sie Ihren Schlüssel nicht in Chat-Nachrichten oder geteilte Dokumente ein.

• Rotieren Sie ihn unter Click & Drop → Settings → API credentials, falls er jemals offengelegt wurde.

Datenschutz & Datenverarbeitung

Dieses MCP läuft vollständig auf Ihrem Rechner. Keine Kundendaten, Anmeldeinformationen oder API-Daten fließen über einen Server, der dem Autor gehört oder von ihm betrieben wird.

Der Datenpfad ist:

• Versanddetails, die Sie Ihrem KI-Assistenten geben, gehen an Ihren KI-Anbieter (z. B. Anthropic, wenn Sie Claude verwenden) unter Ihrem Konto.

• Buchungsanfragen gehen an Royal Mail Click & Drop unter Verwendung Ihres API-Schlüssels.

• Etiketten werden lokal auf Ihrer Festplatte unter ~/Downloads/parcel-toolkit/ gespeichert (änderbar über die Umgebungsvariable PARCEL_TOOLKIT_LABELS_DIR).

Wenn Sie dies in einem britischen Unternehmen verwenden, sind Sie der Datenverantwortliche gemäß UK GDPR. Praktische Empfehlungen:

1. Verwenden Sie Claude Team, Claude Enterprise oder direkt die Claude API — nicht das Consumer-Produkt Claude.ai —, damit eine Datenverarbeitungsvereinbarung (DPA) mit Anthropic besteht. Deaktivieren Sie bei Consumer-Tarifen mindestens "Help improve Claude" in den Datenschutzeinstellungen.

2. Listen Sie Anthropic und Royal Mail als Unterauftragsverarbeiter in Ihrer Datenschutzerklärung auf, genau wie Sie einen Zahlungsanbieter oder E-Mail-Dienst auflisten würden.

3. Vermeiden Sie die Verwendung dieses Tools für Daten besonderer Kategorien (Gesundheits-, biometrische, Kinderdaten) ohne zusätzliche rechtliche Prüfung.

4. Diese Software wird "wie besehen" unter der MIT-Lizenz bereitgestellt. Der Autor ist kein Datenverarbeiter und übernimmt keine Verantwortung für Ihre Compliance-Verpflichtungen — diese liegen bei Ihnen als Datenverantwortlichem.

Mitwirken

Issues und Pull Requests sind willkommen unter github.com/catrinmdonnelly/royalmail-mcp. Wenn Royal Mail ihre API ändert oder Sie auf einen Sonderfall bei Ihrem Kontotyp stoßen, eröffnen Sie bitte ein Issue mit dem gesendeten Request-Body und der erhaltenen Antwort (löschen Sie vorher Ihren API-Schlüssel).

Begleitendes MCP

Für APC Overnight siehe apc-mcp.

Haftungsausschluss

Dieses Projekt ist nicht mit der Royal Mail Group Ltd. verbunden, wird von ihr nicht unterstützt oder gesponsert. "Royal Mail", "Parcelforce" und "Click & Drop" sind Marken ihrer jeweiligen Eigentümer. Nutzung auf eigene Gefahr.

Lizenz

MIT. Siehe LICENSE.