Labelixa

labelixa-mcp

Labelixa 是面向热敏标签开发的 MCP（模型上下文协议）服务和 API 平台。它让 AI 助手和开发工具能够通过 MCP 渲染、验证、调试、检查和转换热敏打印机标签——ZPL、EPL、TSPL 和 CPCL。

有两种连接方式：

	远程服务（推荐）	此 npm 包
端点	https://api.labelixa.com/mcp	通过 stdio 运行本地进程
工具集	完整工具集：渲染、验证、调试、转换、条码分析、打印机兼容性、模板、批量任务	核心子集（见下表）；每个工具都会调用 Labelixa REST API
安装	无需安装	npx -y labelixa-mcp 或 npm install -g labelixa-mcp
身份验证	可选的 lbx_ API 密钥	可选的 lbx_ API 密钥

远程服务的实时工具列表见 labelixa.com/mcp。

远程服务（无需安装）

传输方式：Streamable HTTP，通过 POST 进行无状态 JSON-RPC。匿名使用免费，但会按 IP 限流；使用 API 密钥时会占用账户自身的配额。 密钥：labelixa.com。

Claude Code：

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

使用 API 密钥：

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

通用 MCP 客户端配置（适用于 Claude Desktop、Cursor 及其他接受 url 条目的客户端）：

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

匿名使用时，删除 headers 块。

本地服务（此包）

npm install -g labelixa-mcp

也可以跳过安装，直接在 MCP 客户端配置中通过 npx 运行：

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

环境变量：

• LABELIXA_API_KEY — 可选的 lbx_ API 密钥。不提供时将使用匿名配额。
• LABELIXA_BASE_URL — 可选；默认为 https://api.labelixa.com。

请求绝不会跟随重定向，因此服务无法将你的密钥转发到其他主机。发起请求前会检查数值输入：dpmm 必须为 6、8、12 或 24；标签边长必须为有限值、大于 0 且不超过 15 英寸；DPI 值必须为 152、203、300 或 600。

此软件包中的工具

工具	功能
zpl_preview	将 ZPL 渲染为 PNG 图像以供检查。由服务端渲染，不保证特定实体打印机打印标签时的输出效果。
zpl_validate	检查 ZPL 并以 JSON 格式返回结构化诊断报告（未知命令、参数范围、布局溢出）。请传入实际标签尺寸，检查结果取决于该尺寸。
barcode_generate	生成独立条码（SVG 或 PNG）：code128、code39、ean13、upca、upce、itf14、msi、qrcode、datamatrix、pdf417。
language_detect	检测原始标签代码所使用的打印机语言（ZPL/EPL/TSPL/CPCL）。此检测基于启发式方法，返回置信度等级，而非概率。
epl_validate	检查 EPL/EPL2 代码；以 JSON 格式返回带严重性级别和位置的发现项。
tspl_validate	检查 TSPL/TSPL2 代码；以 JSON 格式返回带严重性级别和位置的发现项。
cpcl_validate	检查 CPCL 代码；以 JSON 格式返回带严重性级别和位置的发现项。
zpl_compatibility	分析 ZPL 与某打印机型号的兼容性风险。这不是模拟器，而是根据证据等级报告语言支持情况；绝不会声称“可以正常工作”。
zpl_command_help	在维护的目录中查询一条 ZPL 命令：名称、语法、参数，以及预览引擎是否实际渲染该命令；打印机端命令会标记为不渲染。可选的 locale（默认 en，也可选 tr、de）仅翻译名称和说明；命令代码、语法字符串、示例和参数名称属于协议内容，绝不会更改。
convert_zpl_dpi	在不同打印机分辨率（203/300/600 dpi）之间缩放 ZPL 坐标。嵌入的 ^GF/~DG 位图不会缩放；存在位图时，输出内容前会附上警告块。
explain_zpl	提供完整的分节健康报告（语法、尺寸/DPI、方向、条码、字体、内存），并给出可信的评分；无法评估的部分会标记为“未评估”，而不会计入评分。

EPL、TSPL 和 CPCL 预览、标签模板、批量生成、图像转 ZPL，以及从照片读取条码，仅在远程服务上提供。

目录列表

• 官方 MCP Registry： com.labelixa/zpl（远程服务 + 此 npm 软件包）。
• Smithery：labelixa/zpl。 Smithery 会通过自己的网关转发调用；规范端点为 https://api.labelixa.com/mcp。

说明

• 错误会原样附带服务端自身的消息；配额用尽时会报告服务端提供的 Retry-After，而不会编造延迟时间。
• zpl_preview 生成的是渲染结果，而非打印结果：实体输出取决于打印机、介质和浓度设置。

此软件包的源码：github.com/Labelixa/labelixa-mcp。 文档：labelixa.com/docs/api。许可证：MIT。