lob-mcp

Ein Model Context Protocol-Server für die Lob.com-API. Ermöglicht jedem MCP-kompatiblen LLM (Claude usw.), Adressen zu verifizieren und physische Post – Postkarten, Briefe, Self-Mailer und gedruckte Schecks – über Lob zu versenden.

⚠️ Lob produziert echte physische Post und belastet Ihr Konto. Tools zum Erstellen von Poststücken (lob_postcards_create, lob_letters_create, lob_self_mailers_create, lob_checks_create, lob_*_orders_create) sind kostenpflichtig. Entwickeln Sie mit einem test_…-API-Schlüssel. Wechseln Sie erst zu live_…, wenn Sie bereit sind, echte Post zu versenden. Übergeben Sie immer einen idempotency_key, damit Wiederholungsversuche nicht zu doppelten Sendungen führen.

Funktionen

• 76 Tools in 12 Ressourcengruppen, die die gesamte Lob v1-API-Oberfläche abdecken:

  • Adressbuch (CRUD)

  • US + internationale Adressverifizierung (einzeln, Massenverarbeitung, Autovervollständigung, Reverse Geocoding, Identitätsvalidierung)

  • Postkarten, Briefe, Self-Mailer, Schecks (erstellen, auflisten, abrufen, stornieren)

  • Vorlagen und Vorlagenversionen (CRUD)

  • Kampagnen und Creatives (CRUD)

  • Beilagen (Buckslips), Karten und deren Druckaufträge

  • Informed Delivery-Kampagnen

  • QR-Code-Analysen

  • Ressourcen-Proofs (Vorschau vor dem Versand)

  • Bankkonten (CRUD + Mikro-Einzahlungs-Verifizierung)

  • USPS-Tracking-Ereignisse

  • Webhook-Abonnements (CRUD)

• Idempotenz-Unterstützung für jeden kostenpflichtigen Erstellungs-Endpunkt

• Test-/Live-Modus-Erkennung anhand des API-Schlüssel-Präfixes, wird beim Start angezeigt

• PII-Schwärzung — Adressfelder werden aus der Fehlerausgabe entfernt

• Generischer extra-Parameter für jedes Erstellungs-/Aktualisierungs-Tool — akzeptiert jeden Lob-Parameter, der nicht im Schema aufgeführt ist, sodass Sie nie durch SDK-Verzögerungen blockiert werden

Anforderungen

• Node.js ≥ 18

• Ein Lob-API-Schlüssel — erhalten Sie einen kostenlosen unter https://dashboard.lob.com/settings/api-keys

Installation

Ausführung via npx (keine Installation)

npx lob-mcp

Global installieren

npm install -g lob-mcp
lob-mcp

Aus dem Quellcode installieren

git clone https://github.com/optimize-overseas/lob-mcp.git
cd lob-mcp
npm install
npm run build
node build/index.js

Konfiguration

Der Server wird vollständig über Umgebungsvariablen konfiguriert.

Verwendung mit Claude Desktop

Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "lob": {
      "command": "npx",
      "args": ["-y", "lob-mcp"],
      "env": {
        "LOB_API_KEY": "test_your_key_here"
      }
    }
  }
}

Starten Sie Claude Desktop neu. Die Lob-Tools sollten in der Tool-Auswahl erscheinen.

Verwendung mit Claude Code

claude mcp add lob --env LOB_API_KEY=test_your_key_here -- npx -y lob-mcp

Verwendung mit dem MCP Inspector

npm run inspector

Öffnen Sie dann die URL, die in Ihrem Terminal ausgegeben wird. Setzen Sie LOB_API_KEY im Umgebungsbereich des Inspectors, bevor Sie Tools aufrufen.

Tool-Referenz

Alle Tools sind unter lob_<resource>_<action> benannt. Annotationshinweise (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) sind gemäß MCP-Spezifikation gesetzt, damit Hosts geeignete Bestätigungsaufforderungen für kostenpflichtige/destruktive Vorgänge anzeigen können.

Adressbuch

• lob_addresses_create · lob_addresses_list · lob_addresses_get · lob_addresses_delete

Adressverifizierung

• lob_us_verifications_create · lob_us_verifications_get

• lob_us_autocompletions_create

• lob_intl_verifications_create

• lob_bulk_us_verifications_create · lob_bulk_intl_verifications_create

• lob_reverse_geocode

• lob_identity_validation

Postkarten (kostenpflichtig bei Erstellung)

• lob_postcards_create · lob_postcards_list · lob_postcards_get · lob_postcards_cancel

Briefe (kostenpflichtig bei Erstellung)

• lob_letters_create · lob_letters_list · lob_letters_get · lob_letters_cancel

Self-Mailer (kostenpflichtig bei Erstellung)

• lob_self_mailers_create · lob_self_mailers_list · lob_self_mailers_get · lob_self_mailers_cancel

Schecks (kostenpflichtig bei Erstellung + zieht Gelder ein)

• lob_checks_create · lob_checks_list · lob_checks_get · lob_checks_cancel

Vorlagen

• lob_templates_create · lob_templates_list · lob_templates_get · lob_templates_update · lob_templates_delete

• lob_template_versions_create · lob_template_versions_list · lob_template_versions_get · lob_template_versions_update · lob_template_versions_delete

Kampagnen + Creatives

• lob_campaigns_create · lob_campaigns_list · lob_campaigns_get · lob_campaigns_update · lob_campaigns_delete

• lob_creatives_create · lob_creatives_list · lob_creatives_get · lob_creatives_update · lob_creatives_delete

Beilagen, Karten und Druckaufträge (Aufträge sind kostenpflichtig)

• lob_buckslips_create · lob_buckslips_list · lob_buckslips_get

• lob_buckslip_orders_create · lob_buckslip_orders_list

• lob_cards_create · lob_cards_list · lob_cards_get

• lob_card_orders_create · lob_card_orders_list

Informed Delivery

• lob_informed_delivery_campaigns_create · lob_informed_delivery_campaigns_list · lob_informed_delivery_campaigns_get

QR-Codes + Ressourcen-Proofs

• lob_qr_codes_list

• lob_resource_proofs_create · lob_resource_proofs_get · lob_resource_proofs_update

Bankkonten (erforderlich für Scheckausstellungen)

• lob_bank_accounts_create · lob_bank_accounts_list · lob_bank_accounts_get · lob_bank_accounts_delete · lob_bank_accounts_verify

Tracking-Ereignisse

• lob_tracking_events_list

Webhooks

• lob_webhooks_create · lob_webhooks_list · lob_webhooks_get · lob_webhooks_update · lob_webhooks_delete

Sicherheitsmodell

Dieser Server erzwingt drei Sicherheitspraktiken, die für eine API mit echtem Geld angemessen sind:

1. Test-/Live-Modus-Erkennung. Der Server prüft beim Start Ihr API-Schlüssel-Präfix und protokolliert den aktiven Modus in stderr. Ein test_…-Schlüssel produziert keine echte Post; ein live_…-Schlüssel produziert echte, kostenpflichtige Post.

2. Idempotenz. Jedes kostenpflichtige Erstellungs-Tool bietet einen optionalen idempotency_key-Parameter. Übergeben Sie eine UUID (oder eine beliebige eindeutige Zeichenfolge bis zu 256 Zeichen) pro logischer Anfrage. Lob gibt für jede nachfolgende Anfrage, die denselben Schlüssel verwendet, die ursprüngliche Antwort zurück, um doppelte Post bei Netzwerk-Wiederholungsversuchen zu verhindern.

3. PII-Schwärzung in Fehlern. Adress-, Namens- und Kontaktfelder werden aus jedem Fehler-Payload entfernt, der an den Client zurückgegeben wird. Der vollständige Anfragetext wird niemals protokolliert; nur Fehlermetadaten (Status, Code, Anfrage-ID, Nachricht) werden angezeigt.

Der extra-Notausgang

Die API von Lob bietet viele ressourcenspezifische Optionen, die nicht in einem Tool-Schema aufgezählt werden müssen (benutzerdefinierte Umschlag-IDs, Perforationsseiten, Abrechnungsgruppen, Marketing-Flags usw.). Jedes Erstellungs-/Aktualisierungs-Tool akzeptiert ein optionales extra-Objekt, dessen Schlüssel wortwörtlich in den Anfragetext eingefügt werden:

{
  "to": "adr_123…",
  "from": "adr_456…",
  "front": "<html>…</html>",
  "back": "<html>…</html>",
  "extra": {
    "billing_group_id": "bg_…",
    "use_type": "marketing"
  }
}

Siehe https://docs.lob.com/ für die vollständige Liste der Parameter pro Ressource.

Entwicklung

npm install
npm run build
npm run typecheck
npm run inspector

Die kompilierte Ausgabe befindet sich in build/. Der Quellcode liegt in src/.

Architektur

src/
├── index.ts            # stdio entry — boots McpServer + LobClient
├── env.ts              # env loading + test/live mode detection
├── lob/
│   ├── client.ts       # fetch-based HTTP client (Basic auth, idempotency, errors)
│   ├── errors.ts       # LobApiError + tool-friendly formatter
│   └── redact.ts       # PII redaction
├── schemas/
│   ├── common.ts       # address, pagination, idempotency, metadata schemas
│   └── mail.ts         # mail-piece-shared schemas
└── tools/
    ├── helpers.ts      # registerTool helper with consistent error mapping
    ├── register.ts     # wires every group into the server
    └── *.ts            # one file per resource group

Der HTTP-Client ist bewusst schlank gehalten — er hängt nicht vom offiziellen lob-typescript-sdk ab, was die Abhängigkeitsoberfläche klein hält und diesem Server eine engere Kontrolle über Header, Wiederholungsversuche und PII-Handhabung gibt. Neue Lob-Endpunkte können hinzugefügt werden, indem ein weiteres Tool für die Ressourcengruppe registriert wird (oder über den extra-Notausgang bei bestehenden Tools).

Einschränkungen

• Multipart-Datei-Uploads für Ressourcen, die binäre PDF-/Bild-Bytes akzeptieren, werden vom zugrunde liegenden Client unterstützt (asForm: true), sind aber noch in keinem Tool verfügbar — die aktuellen Tools akzeptieren HTML-Strings, URLs, Vorlagen-IDs und Base64-Daten-URIs, was die dokumentierten Lob-Inhaltsquellen abdeckt.

• OAuth wird nicht unterstützt, da Lob dies nicht anbietet; die Authentifizierung erfolgt gemäß Lob-Dokumentation über HTTP Basic mit einem API-Schlüssel.

Mitwirken

Probleme und Pull Requests sind willkommen unter https://github.com/optimize-overseas/lob-mcp.

Lizenz

MIT — siehe LICENSE.

Haftungsausschluss

Dieses Projekt ist nicht mit Lob.com verbunden, wird von Lob.com nicht unterstützt oder gesponsert. "Lob" ist eine Marke von Lob.com, Inc. Die Nutzung der Lob-API unterliegt den Nutzungsbedingungen und der Richtlinie zur akzeptablen Nutzung von Lob.