Labelixa

Official21 tools

by Labelixa · JavaScript

Thermal label MCP server: render, validate, debug and convert ZPL, EPL, TSPL and CPCL labels.

Model Context Protocol (MCP) Server: com.labelixa/zpl

The com.labelixa/zpl MCP server provides tools to render, validate, and convert Zebra ZPL label code produced by AI assistants. It supports generating a PNG preview, performing lint checks, and handling barcodes as part of the label workflow.

🛠️ Key Features

Render Zebra ZPL label code
Validate Zebra ZPL label code
Convert Zebra ZPL label code from AI assistants
Generate PNG preview
Lint Zebra ZPL
Barcodes support
Tool count: 8

🚀 Use Cases

Preview Zebra ZPL output as PNG
Validate and lint ZPL before use
Convert AI-generated ZPL into usable label artifacts, including barcodes

⚡ Developer Benefits

Structured tooling for render/validate/convert
Immediate visual feedback via PNG preview
Automated linting for Zebra ZPL

⚠️ Limitations

Limited to Zebra ZPL label code rendering, validation, conversion, preview, linting, and barcodes.

Topics

barcodecpclepllabel-printingmcpmcp-servermodel-context-protocolthermal-printertsplzebrazpl

Captured live from the server via tools/list.

zpl_preview

Render ZPL label code and return the label as a PNG image. Use this to SEE what ZPL output looks like — LLMs can write ZPL but cannot otherwise verify the visual result. One call renders one label (use `index` to pick a label from a multi-label stream). The result also carries an 'Open this label in the Labelixa editor' link the user can click to edit, save or share the label.

Parameters5

zpl	string	required	ZPL source (^XA...^XZ)
dpmm	integer	optional	Printer density (8 = 203 dpi)
width_in	number	optional	Label width, inches
height_in	number	optional	Label height, inches
index	integer	optional	Label index in the stream

Raw schema

{
  "type": "object",
  "properties": {
    "zpl": {
      "type": "string",
      "description": "ZPL source (^XA...^XZ)"
    },
    "dpmm": {
      "type": "integer",
      "enum": [
        6,
        8,
        12,
        24
      ],
      "default": 8,
      "description": "Printer density (8 = 203 dpi)"
    },
    "width_in": {
      "type": "number",
      "default": 4,
      "description": "Label width, inches"
    },
    "height_in": {
      "type": "number",
      "default": 6,
      "description": "Label height, inches"
    },
    "index": {
      "type": "integer",
      "default": 0,
      "description": "Label index in the stream"
    }
  },
  "required": [
    "zpl"
  ]
}

zpl_validate

Lint ZPL code and return structured diagnostics: unknown commands, missing ^FS, out-of-range parameters, fields outside the label boundary. Run this before zpl_preview when generating ZPL.

Parameters4

zpl	string	required	ZPL source
dpmm	integer	optional	Printer density (8 = 203 dpi). The boundary check measures against it — pass the real value.
width_in	number	optional	Label width in inches. Fields outside it are reported, so a wrong size makes that finding wrong.
height_in	number	optional	Label height in inches. Same as width_in: the boundary check depends on it.

Raw schema

{
  "type": "object",
  "properties": {
    "zpl": {
      "type": "string",
      "description": "ZPL source"
    },
    "dpmm": {
      "type": "integer",
      "default": 8,
      "description": "Printer density (8 = 203 dpi). The boundary check measures against it — pass the real value."
    },
    "width_in": {
      "type": "number",
      "default": 4,
      "description": "Label width in inches. Fields outside it are reported, so a wrong size makes that finding wrong."
    },
    "height_in": {
      "type": "number",
      "default": 6,
      "description": "Label height in inches. Same as width_in: the boundary check depends on it."
    }
  },
  "required": [
    "zpl"
  ]
}

zpl_command_help

Explain a single ZPL command: syntax, parameters with types/ranges/options, a fragment example and whether the Labelixa renderer draws it. Data comes from the same catalog that powers the public command reference pages.

Parameters2

command	string	required	ZPL command code, e.g. FO, ^BC, ~DG
locale	string	optional	Language for the human-readable fields (name and descriptions). Command codes, syntax strings, examples and parameter names never change.

Raw schema

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "description": "ZPL command code, e.g. FO, ^BC, ~DG"
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "tr",
        "de"
      ],
      "default": "en",
      "description": "Language for the human-readable fields (name and descriptions). Command codes, syntax strings, examples and parameter names never change."
    }
  },
  "required": [
    "command"
  ]
}

barcode_png

Generate a single barcode as a PNG image (Code 128, QR, DataMatrix, EAN-13, UPC-A, PDF417 and more). For a full label with text and layout, write ZPL and use zpl_preview instead.

Parameters2

type	string	optional	Symbology (code128, qr, datamatrix, ean13, upca, pdf417...)
data	string	required	Data to encode

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "default": "code128",
      "description": "Symbology (code128, qr, datamatrix, ean13, upca, pdf417...)"
    },
    "data": {
      "type": "string",
      "description": "Data to encode"
    }
  },
  "required": [
    "data"
  ]
}

language_detect

Detect which printer language raw label code is written in (ZPL, EPL, TSPL or CPCL). Heuristic: returns the language plus a confidence TIER (high/medium/low) and signal codes — not a probability.

Parameters1

code

string

required

Raw label code to classify

Raw schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Raw label code to classify"
    }
  },
  "required": [
    "code"
  ]
}

epl_validate

Lint EPL/EPL2 label code and return positioned findings with severity as JSON. Checks the command set Labelixa implements from the EPL2 manual — a clean result is not a guarantee that a specific printer accepts the job. Run this before epl_preview; if you are not sure which language the code is, call language_detect first.

Parameters1

epl

string

required

Raw EPL/EPL2 code

Raw schema

{
  "type": "object",
  "properties": {
    "epl": {
      "type": "string",
      "description": "Raw EPL/EPL2 code"
    }
  },
  "required": [
    "epl"
  ]
}

tspl_validate

Lint TSPL/TSPL2 label code and return positioned findings with severity as JSON. Checks the command set Labelixa implements from the TSPL2 manual — a clean result is not a guarantee that a specific printer accepts the job. Run this before tspl_preview; if you are not sure which language the code is, call language_detect first.

Parameters1

tspl

string

required

Raw TSPL/TSPL2 code

Raw schema

{
  "type": "object",
  "properties": {
    "tspl": {
      "type": "string",
      "description": "Raw TSPL/TSPL2 code"
    }
  },
  "required": [
    "tspl"
  ]
}

cpcl_validate

Lint CPCL label code and return positioned findings with severity as JSON. Checks the command set Labelixa implements from the CPCL manual — a clean result is not a guarantee that a specific printer accepts the job. Run this before cpcl_preview; if you are not sure which language the code is, call language_detect first.

Parameters1

cpcl

string

required

Raw CPCL code

Raw schema

{
  "type": "object",
  "properties": {
    "cpcl": {
      "type": "string",
      "description": "Raw CPCL code"
    }
  },
  "required": [
    "cpcl"
  ]
}

explain_zpl

Full health report for a ZPL label: sectioned findings (syntax, size/DPI, orientation, barcodes, fonts, graphics memory, job behaviour) with an honest score — sections that cannot be assessed say so and are excluded from the score.

Parameters4

zpl	string	required	Raw ZPL code
dpmm	integer	optional	Printer density (8 = 203 dpi). The size/DPI section is scored against it — pass the real value.
width_in	number	optional	Label width in inches; fields outside it are reported.
height_in	number	optional	Label height in inches; same role as width_in.

Raw schema

{
  "type": "object",
  "properties": {
    "zpl": {
      "type": "string",
      "description": "Raw ZPL code"
    },
    "dpmm": {
      "type": "integer",
      "enum": [
        6,
        8,
        12,
        24
      ],
      "default": 8,
      "description": "Printer density (8 = 203 dpi). The size/DPI section is scored against it — pass the real value."
    },
    "width_in": {
      "type": "number",
      "default": 4,
      "description": "Label width in inches; fields outside it are reported."
    },
    "height_in": {
      "type": "number",
      "default": 6,
      "description": "Label height in inches; same role as width_in."
    }
  },
  "required": [
    "zpl"
  ]
}

convert_zpl_dpi

Rescale ZPL between printer resolutions (203/300/600 DPI): coordinates, fonts, barcode module width and label size are scaled. Embedded ^GF/~DG image data is NOT scaled; the response says so instead of silently passing it through.

Parameters3

zpl	string	required	Raw ZPL code
source_dpi	integer	required	Resolution the ZPL was written for, in DPI (not dpmm: 203 DPI = 8 dpmm).
target_dpi	integer	required	Resolution to rescale to, in DPI. Equal to source_dpi means no scaling.

Raw schema

{
  "type": "object",
  "properties": {
    "zpl": {
      "type": "string",
      "description": "Raw ZPL code"
    },
    "source_dpi": {
      "type": "integer",
      "enum": [
        152,
        203,
        300,
        600
      ],
      "description": "Resolution the ZPL was written for, in DPI (not dpmm: 203 DPI = 8 dpmm)."
    },
    "target_dpi": {
      "type": "integer",
      "enum": [
        152,
        203,
        300,
        600
      ],
      "description": "Resolution to rescale to, in DPI. Equal to source_dpi means no scaling."
    }
  },
  "required": [
    "zpl",
    "source_dpi",
    "target_dpi"
  ]
}

template_list

List Labelixa's first-party label template catalog: id, English name, category, size/density and tags. Read-only product content (no tenant data). Fetch one with template_get; render its ZPL with zpl_preview.

Parameters2

category	string	optional	Filter by category
search	string	optional	Substring match on id/tags

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "kargo",
        "urun",
        "raf",
        "palet",
        "qr"
      ],
      "description": "Filter by category"
    },
    "search": {
      "type": "string",
      "description": "Substring match on id/tags"
    }
  }
}

template_get

Fetch one catalog template: metadata, preview image URL and — for non-premium templates — the ZPL source, ready for zpl_preview. Premium templates return metadata for everyone; their ZPL source requires an API key whose plan includes the premium-template feature (same rule as the website).

Parameters1

template_id

string

required

Template id from template_list

Raw schema

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "description": "Template id from template_list"
    }
  },
  "required": [
    "template_id"
  ]
}

epl_preview

Render EPL/EPL2 label code and return a PNG preview. The preview assumes 203 dpi and is an interpretation of the EPL2 manual covering a core command subset — no physical printer validation. `labels` in the response is the TOTAL number of labels the stream prints (a stream may contain several, each ended by `P`); pass `index` to render a different one.

Parameters2

epl	string	required	Raw EPL/EPL2 code
index	integer	optional	Label index in the stream

Raw schema

{
  "type": "object",
  "properties": {
    "epl": {
      "type": "string",
      "description": "Raw EPL/EPL2 code"
    },
    "index": {
      "type": "integer",
      "default": 0,
      "description": "Label index in the stream"
    }
  },
  "required": [
    "epl"
  ]
}

tspl_preview

Render TSPL/TSPL2 label code and return a PNG preview. The preview assumes 203 dpi and is an interpretation of the TSPL manual covering a core command subset — no physical printer validation. `labels` in the response is the TOTAL number of labels the stream prints (a stream may contain several, each ended by `PRINT`); pass `index` to render a different one.

Parameters2

tspl	string	required	Raw TSPL/TSPL2 code
index	integer	optional	Label index in the stream

Raw schema

{
  "type": "object",
  "properties": {
    "tspl": {
      "type": "string",
      "description": "Raw TSPL/TSPL2 code"
    },
    "index": {
      "type": "integer",
      "default": 0,
      "description": "Label index in the stream"
    }
  },
  "required": [
    "tspl"
  ]
}

cpcl_preview

Render CPCL label code and return a PNG preview. The preview assumes 203 dpi and is an interpretation of the CPCL manual covering a core command subset — no physical printer validation. `labels` in the response is the TOTAL number of labels the stream prints (a stream may contain several, each ended by `PRINT`); pass `index` to render a different one.

Parameters2

cpcl	string	required	Raw CPCL code
index	integer	optional	Label index in the stream

Raw schema

{
  "type": "object",
  "properties": {
    "cpcl": {
      "type": "string",
      "description": "Raw CPCL code"
    },
    "index": {
      "type": "integer",
      "default": 0,
      "description": "Label index in the stream"
    }
  },
  "required": [
    "cpcl"
  ]
}

image_to_zpl

Convert an image (PNG, JPEG, BMP or GIF, max 200 KB) to a ZPL ^GF graphic command. Returns the ZPL plus measured dimensions and the physical print size at the chosen density. PDF input is REST-only (/v1/graphics).

Parameters4

image_base64	string	required	Base64-encoded image bytes
dpmm	integer	optional	Target printer density
wrap	boolean	optional	Wrap the ^GF in a printable ^XA...^XZ label with ^PW/^LL
dither	boolean	optional	Dither instead of hard threshold (photos)

Raw schema

{
  "type": "object",
  "properties": {
    "image_base64": {
      "type": "string",
      "description": "Base64-encoded image bytes"
    },
    "dpmm": {
      "type": "integer",
      "enum": [
        6,
        8,
        12,
        24
      ],
      "default": 8,
      "description": "Target printer density"
    },
    "wrap": {
      "type": "boolean",
      "default": false,
      "description": "Wrap the ^GF in a printable ^XA...^XZ label with ^PW/^LL"
    },
    "dither": {
      "type": "boolean",
      "default": false,
      "description": "Dither instead of hard threshold (photos)"
    }
  },
  "required": [
    "image_base64"
  ]
}

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. Honest by design: 'read' does not guarantee every handheld scanner will read it, and 'not read' does not condemn the label (photo angle/focus matter) — the response says so.

Parameters1

image_base64

string

required

Base64-encoded image bytes

Raw schema

{
  "type": "object",
  "properties": {
    "image_base64": {
      "type": "string",
      "description": "Base64-encoded image bytes"
    }
  },
  "required": [
    "image_base64"
  ]
}

zpl_compatibility

Compatibility RISK analysis of ZPL code against a specific printer model, given as manufacturer/model (e.g. 'zebra/zd421'). NOT an emulator and never says 'it works': reports the model's language posture with evidence level and size-rule findings.

Parameters2

zpl	string	required	Raw ZPL code
model	string	required	Printer model slug, manufacturer/model, e.g. zebra/zd421

Raw schema

{
  "type": "object",
  "properties": {
    "zpl": {
      "type": "string",
      "description": "Raw ZPL code"
    },
    "model": {
      "type": "string",
      "description": "Printer model slug, manufacturer/model, e.g. zebra/zd421"
    }
  },
  "required": [
    "zpl",
    "model"
  ]
}

bulk_submit

Submit a bulk label production job: one ZPL template with {{variable}} placeholders plus data rows (one object per label). Requires an API key whose plan includes bulk jobs. Quota is charged UPFRONT, one operation per row, and failed rows are not refunded; rows per job are capped by plan. Returns the job id — check bulk_status (small jobs usually finish within seconds).

Parameters6

zpl	string	required	ZPL template with {{name}} placeholders
rows	array	required	One object per label: placeholder name -> value
output	string	optional	Output format (default zpl)
dpmm	integer	optional	Print density (default 8)
width_in	number	optional	Label width, inches
height_in	number	optional	Label height, inches

Raw schema

{
  "type": "object",
  "properties": {
    "zpl": {
      "type": "string",
      "description": "ZPL template with {{name}} placeholders"
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        }
      },
      "description": "One object per label: placeholder name -> value"
    },
    "output": {
      "type": "string",
      "enum": [
        "zpl",
        "png",
        "pdf"
      ],
      "description": "Output format (default zpl)"
    },
    "dpmm": {
      "type": "integer",
      "enum": [
        6,
        8,
        12,
        24
      ],
      "description": "Print density (default 8)"
    },
    "width_in": {
      "type": "number",
      "description": "Label width, inches"
    },
    "height_in": {
      "type": "number",
      "description": "Label height, inches"
    }
  },
  "required": [
    "zpl",
    "rows"
  ]
}

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). Finished outputs stay downloadable for 7 days via the REST endpoint the response names.

Parameters1

job_id

string

required

Job id from bulk_submit

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "Job id from bulk_submit"
    }
  },
  "required": [
    "job_id"
  ]
}

bulk_list

List your recent bulk jobs (id, state, error class, timestamps), newest first. Useful to recover a lost job id; details via bulk_status.

Parameters1

limit

integer

optional

Max jobs to return (default 50)

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "Max jobs to return (default 50)"
    }
  }
}

README.md5 KBView on GitHub

labelixa-mcp

Labelixa is an MCP (Model Context Protocol) server and API platform for thermal label development. It gives AI assistants and developer tools the ability to render, validate, debug, inspect and convert thermal printer labels — ZPL, EPL, TSPL and CPCL — through MCP.

There are two ways to connect:

	Remote server (recommended)	This npm package
Endpoint	`https://api.labelixa.com/mcp`	local process over stdio
Tool set	full set: rendering, validation, debugging, conversion, barcode analysis, printer compatibility, templates, bulk jobs	core subset (table below); each tool calls the Labelixa REST API
Install	nothing to install	`npx -y labelixa-mcp` or `npm install -g labelixa-mcp`
Authentication	optional `lbx_` API key	optional `lbx_` API key

The live tool list of the remote server is at labelixa.com/mcp.

Remote server (no install)

Transport: Streamable HTTP, stateless JSON-RPC over POST. Anonymous use is free and rate-limited per IP; an API key uses the account's own quota. Keys: labelixa.com.

Claude Code:

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

With an API key:

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

Generic MCP client configuration (Claude Desktop, Cursor and other clients that accept a url entry):

json

{
  "mcpServers": {
    "labelixa": {
      "url": "https://api.labelixa.com/mcp",
      "headers": {"Authorization": "Bearer lbx_..."}
    }
  }
}

Drop the headers block for anonymous use.

Local server (this package)

npm install -g labelixa-mcp

Or skip installing and run it with npx straight from your MCP client config:

json

{
  "mcpServers": {
    "labelixa": {
      "command": "npx",
      "args": ["-y", "labelixa-mcp"],
      "env": {"LABELIXA_API_KEY": "lbx_..."}
    }
  }
}

Environment variables:

LABELIXA_API_KEY — optional lbx_ API key. Without it the anonymous quota applies.
LABELIXA_BASE_URL — optional; defaults to https://api.labelixa.com.

Requests never follow redirects, so a server cannot forward your key to another host. Numeric inputs are checked before a request is made: dpmm is 6, 8, 12 or 24, label sides are finite, above 0 and at most 15 inches, and DPI values are 152, 203, 300 or 600.

Tools in this package

Tool	What it does
`zpl_preview`	Renders ZPL to a PNG image for inspection. Server-side render — not a guarantee of how a specific physical printer will output the label.
`zpl_validate`	Lints ZPL and returns the structured diagnostics report (unknown commands, parameter ranges, layout overflow) as JSON. Pass the real label size — checks depend on it.
`barcode_generate`	Generates a standalone barcode (SVG or PNG): code128, code39, ean13, upca, upce, itf14, msi, qrcode, datamatrix, pdf417.
`language_detect`	Detects the printer language of raw label code (ZPL/EPL/TSPL/CPCL). Heuristic — returns a confidence tier, not a probability.
`epl_validate`	Lints EPL/EPL2 code; positioned findings with severity, as JSON.
`tspl_validate`	Lints TSPL/TSPL2 code; positioned findings with severity, as JSON.
`cpcl_validate`	Lints CPCL code; positioned findings with severity, as JSON.
`zpl_compatibility`	Compatibility RISK analysis of ZPL against a printer model. Not an emulator — reports language posture with evidence level; never says "it works".
`zpl_command_help`	Looks up one ZPL command in the maintained catalog: name, syntax, parameters and whether the preview engine actually renders it — printer-side commands are marked as not rendered. Optional `locale` (`en` default, `tr`, `de`) translates the name and descriptions only; command codes, syntax strings, examples and parameter names are protocol and never change.
`convert_zpl_dpi`	Rescales ZPL coordinates between printer resolutions (203/300/600 dpi). Embedded `^GF`/`~DG` bitmaps are NOT rescaled — a warnings block precedes the output when present.
`explain_zpl`	Full sectioned health report (syntax, size/DPI, orientation, barcodes, fonts, memory) with an honest score — sections it cannot assess say "not assessed" instead of counting.

EPL, TSPL and CPCL previews, label templates, bulk generation, image-to-ZPL conversion and barcode reading from photos are on the remote server only.

Directory listings

Official MCP Registry: com.labelixa/zpl (remote server + this npm package).
Smithery: labelixa/zpl. Smithery routes calls through its own gateway; the canonical endpoint is https://api.labelixa.com/mcp.

smithery badge

Honesty notes

Errors carry the server's own message verbatim; quota exhaustion is reported with the server's Retry-After rather than a made-up delay.
zpl_preview is a render, not a print: physical output depends on the printer, media and darkness settings.

Source of this package: github.com/Labelixa/labelixa-mcp. Docs: labelixa.com/docs/api. License: MIT.

Install

Tools (21)

zpl_previewzpl_validatezpl_command_helpbarcode_pnglanguage_detectepl_validatetspl_validatecpcl_validate

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "zpl": {
      "command": "npx",
      "args": [
        "-y",
        "labelixa-mcp@0.4.1"
      ]
    }
  }
}

Model Context Protocol (MCP) Server: com.labelixa/zpl

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

zpl_preview

zpl_validate

zpl_command_help

barcode_png

language_detect

epl_validate

tspl_validate

cpcl_validate

explain_zpl

convert_zpl_dpi

template_list

template_get

epl_preview

tspl_preview

cpcl_preview

image_to_zpl

barcode_verify

zpl_compatibility

bulk_submit

bulk_status

bulk_list

labelixa-mcp

Remote server (no install)

Local server (this package)

Tools in this package

Directory listings

Honesty notes

Install

Related servers