Startseite›Entwickler›MCP-Server

MCP-Server

Labelixa betreibt einen Remote-MCP-Server (Model Context Protocol): MCP-kompatible KI-Clients können Thermo-Etikettencode — ZPL, EPL, TSPL und CPCL — als vollwertige Werkzeuge rendern, validieren, debuggen, konvertieren und Barcodes erzeugen. Verifiziert mit Claude Desktop und Claude Code; jeder MCP-kompatible Client kann sich verbinden.

Konfiguration

Fügen Sie den Server Ihrem MCP-kompatiblen Client hinzu (Claude-Desktop-Format gezeigt). Lokale stdio-Alternative auf npm: labelixa-mcp.

{
  "mcpServers": {
    "labelixa": {
      "type": "http",
      "url": "https://api.labelixa.com/mcp"
    }
  }
}

Claude Code, eine Zeile im Terminal:

claude mcp add --transport http labelixa https://api.labelixa.com/mcp

Mit API-Schlüssel (derselbe Authorization-Header funktioniert im JSON-Client-Eintrag unter "headers"):

claude mcp add --transport http labelixa https://api.labelixa.com/mcp --header "Authorization: Bearer lbx_YOUR_KEY"

Beispiel-Prompts

Nach dem Verbinden fragen Sie in normaler Sprache — das Werkzeug wählt der Client. Jeder Prompt unten wurde gegen diesen Server ausgeführt:

Validiere dieses ZPL und erkläre die Diagnose: ^XA^FO40,40^A0N,40,40^FDHallo^FS^XZ
Rendere dieses ZPL und zeig mir das Etikett.
Was macht ^BC, und zeichnet Labelixas Vorschau es?
In welcher Druckersprache ist dieser Code geschrieben?
Erzeuge ein QR-Code-PNG für https://labelixa.com/mcp

Clients

Konfigurations-Schnipsel veröffentlichen wir nur für Clients, die wir selbst getestet haben. Die übrigen sind keine Absage: Jeder Client, der Remote-MCP über streamable HTTP spricht, braucht nichts außer dem Endpunkt oben — wir haben sie schlicht nicht ausgeführt und beschreiben kein Setup, das wir nicht funktionieren sahen.

Client	Status
Claude Desktop	Von uns getestet
Claude Code	Von uns getestet
Cursor	Von uns nicht getestet
VS Code	Von uns nicht getestet
Windsurf	Von uns nicht getestet
ChatGPT / Codex	Von uns nicht getestet
Gemini CLI	Von uns nicht getestet

Verfügbare Werkzeuge

Die Werkzeuge, die der Server HEUTE anbietet — die Liste wird aus der Live-Registrierung erzeugt, nicht von Hand gepflegt:

zpl_preview — Render ZPL label code and return the label as a PNG image.
zpl_validate — Pass/fail lint for ZPL — machine-readable diagnostics with line/column, code and severity: unknown commands, missing ^FS, out-of-range parameters, fields outside the label.
zpl_command_help — Explain a single ZPL command: syntax, parameters with types/ranges/options, a fragment example and whether the Labelixa renderer draws it.
barcode_png — Generate a single barcode as a PNG image (Code 128, QR, DataMatrix, EAN-13, UPC-A, PDF417 and more).
language_detect — Detect which printer language raw label code is written in (ZPL, EPL, TSPL or CPCL).
epl_validate — Lint EPL/EPL2 label code and return positioned findings with severity as JSON.
tspl_validate — Lint TSPL/TSPL2 label code and return positioned findings with severity as JSON.
cpcl_validate — Lint CPCL label code and return positioned findings with severity as JSON.
explain_zpl — Human-readable health REPORT for a finished ZPL label, with a 0-100 score: sectioned findings (syntax, size/DPI, orientation, barcodes, fonts, graphics memory, job behaviour); sections that cannot be assessed say so and are excluded from the score.
convert_zpl_dpi — Rescale ZPL between printer resolutions (203/300/600 DPI): coordinates, fonts, barcode module width and label size are scaled.
template_list — List Labelixa's first-party label template catalog: id, English name, category, size/density and tags.
template_get — Fetch one catalog template: metadata, preview image URL and — for non-premium templates — the ZPL source, ready for zpl_preview.
save_label — Save a ZPL label to a Labelixa account so it can be edited, versioned and printed later.
epl_preview — Render EPL/EPL2 label code and return a PNG preview.
tspl_preview — Render TSPL/TSPL2 label code and return a PNG preview.
cpcl_preview — Render CPCL label code and return a PNG preview.
image_to_zpl — Convert an image (PNG, JPEG, BMP or GIF, max 200 KB) to a ZPL ^GF graphic command.
barcode_verify — Decode barcodes from a photo or scan of a PRINTED label (PNG, JPEG, BMP or GIF) and report what a software decoder reads back.
zpl_compatibility — Compatibility RISK analysis of ZPL code against a specific printer model, given as manufacturer/model (e.g.
bulk_submit — Submit a bulk label production job: one ZPL template with {{variable}} placeholders plus data rows (one object per label).
bulk_status — Status of one bulk job you own: state, attempt count and — when finished — the summary with produced count and per-row failures (row number + reason; failed rows never block the rest).
bulk_list — List your recent bulk jobs (id, state, error class, timestamps), newest first.
printer_language_to_zpl — Convert a SATO SBPL, Honeywell (Datamax) DPL or Honeywell (Intermec) IPL label stream to ZPL, so it can be checked with zpl_validate and rendered with zpl_preview.

Endpunkt

Streamable HTTP (JSON-RPC): https://api.labelixa.com/mcp. GET liefert diese Seite; das Protokoll spricht über POST.

Authentifizierung und Kontingente

Kein Schlüssel nötig: anonyme Aufrufe teilen die kostenlose, pro IP ratenbegrenzte Stufe. Senden Sie Ihren Schlüssel im X-API-Key-Header (oder als Bearer-Token), um das Kontingent Ihres Tarifs zu nutzen. MCP-Aufrufe durchlaufen dieselben Raten- und Kontingent-Tore wie die REST-API — MCP ist kein Kontingent-Bypass.

Was nach dem Verbinden passiert

Der Client ruft tools/list auf und die Werkzeuge oben erscheinen neben seinen eigenen. Ein Werkzeugaufruf nimmt denselben Weg wie die REST-API — gleiche Authentifizierung, gleiche Ratenlimits, gleiche Kontingentzähler — und liefert entweder Text (JSON-Diagnose) oder ein PNG, das der Client inline anzeigt. Zwischen den Aufrufen wird nichts gespeichert: der Server ist zustandslos, jeder Aufruf steht für sich.

Grenzen

Streamable HTTP nur über POST. Ein GET mit Accept: text/event-stream antwortet 405 mit Allow: POST — es gibt keinen SSE-Sitzungskanal.
Anfrage-Umschlag: 2 MB. Bildeingabe für image_to_zpl: 200 KB; für barcode_verify: 5 MB.
zpl_preview ist ein SERVERSEITIGES Rendering zur Prüfung, keine Garantie für die Ausgabe eines bestimmten physischen Druckers.
Werkzeuge hinter einem geschlossenen Feature-Flag fehlen in tools/list und antworten beim Aufruf mit "unbekanntes Werkzeug" — die Liste ist der Vertrag.
Bulk-Jobs lassen sich über MCP einreichen und abfragen; die erzeugte Ausgabe wird über die REST-API geladen.

Fehlerbehebung

404 am Endpunkt — das Server-Flag ist geschlossen; auf Ihrer Seite gibt es nichts zu konfigurieren.
405 bei GET — erwartet. Das Protokoll spricht per POST.
Ratenlimit (429, z. B. "3/s") — anonyme Aufrufe sind pro IP begrenzt. Langsamer aufrufen oder einen API-Schlüssel senden, um das Tarif-Kontingent zu nutzen.
"Unbekanntes Werkzeug" — der Name steht nicht in tools/list (Tippfehler oder ein Flag-gesteuertes Werkzeug).
Ein Werkzeug antwortet mit Fehler statt Ergebnis — der Text ist die Meldung des Servers, unverändert durchgereicht. Er sagt, was fehlschlug; wir schreiben ihn nicht um.

Sicherheit und Datenschutz

Werkzeugaufrufe folgen demselben zustandslosen Pfad wie die REST-API: gesendeter Etikettencode wird im Speicher verarbeitet und zurückgegeben, nicht gespeichert. Details auf der Sicherheitsseite.