barcoding-mcp

An MCP server that encodes 100+ barcode symbologies (via bwip-js) and decodes all the common 1D/2D formats (via zxing-wasm), with zero native dependencies. Node runtime, served over both stdio and streamable HTTP. Plus an ASCII/Unicode terminal QR for output that needs no image channel.

The funnel is asymmetric on purpose: encode 100+, decode the common set, round-trip-verified where both overlap. We do not claim "decode anything."

Direction	Library	Coverage
Encode	bwip-js	100+ symbologies (full BWIPP)
Decode	zxing-wasm	~20 common 1D/2D (QR, Micro QR, DataMatrix, Aztec, PDF417, MaxiCode, Code128/39/93, EAN/UPC, ITF, Codabar, DataBar)
Terminal QR	qrcode	block-character QR, pure text

Tools

Tool	Purpose
encode_barcode	Render a barcode (bcid + text + typed common options + freeform options bag). Returns a PNG.
encode_qr_terminal	Encode data to a block-character QR. style: unicode (default, safe in codeblocks/logs) or ansi (live TTY).
decode_barcode	Detect + decode 1D/2D barcodes from an image (base64 / path / url; PNG or JPEG).
decode_batch	Decode many images in one call; per-item results, isolated errors.
decode_pdf	Rasterize a PDF (mupdf WASM) and pull every barcode, tagged with page number.
gs1_parse	Parse a decoded GS1 string into structured Application Identifiers (GTIN, dates, batch, serial, weights…).
verify_barcode	Encode → decode the render → assert the payload round-trips. Self-verifying label QA.
list_symbologies	Supported symbologies flagged encode / decode / both.
list_symbology_options	Valid encode options for a bcid, segmented specific / common / sizing. Discover the options bag's keys before encoding.

Install & run

npm (stdio — for Claude Code, Cursor, local agents)

npx @cordfuse/barcoding-mcp          # stdio transport (default)
npx @cordfuse/barcoding-mcp --http   # streamable HTTP on :3900

MCP client config (stdio):

{
  "mcpServers": {
    "barcoding": { "command": "npx", "args": ["-y", "@cordfuse/barcoding-mcp"] }
  }
}

Docker / GHCR (streamable HTTP — for remote / metamcp wiring)

docker run -p 3900:3900 ghcr.io/cordfuse/barcoding-mcp:latest
# or, from a checkout:
docker compose -f docker/compose.yaml up

Serves streamable HTTP at http://<host>:3900/mcp, with a liveness probe at /health. Port is settable via the PORT env. stdio is per-invocation and not containerised — the image is the HTTP endpoint.

Repository layout (monorepo)

barcoding-mcp/
  packages/
    mcp/          @cordfuse/barcoding-mcp  (the server)  →  packages/mcp/README.md
  docker/         Dockerfile + compose.yaml (the --http server)
  .github/        CI + release workflows

npm workspace; node_modules hoists to the root.

Development

npm ci                                     # install (root)
npm run build   -w @cordfuse/barcoding-mcp # tsc + copy option catalog into dist
npm test        -w @cordfuse/barcoding-mcp # node:test smoke suite
npm run gen:options -w @cordfuse/barcoding-mcp  # regenerate the option catalog from bwip-js

The list_symbology_options catalog is generated from bwip-js's own sources (dist/bwip-js-gen.d.ts for common options, barcode.ps for the per-symbology option preambles) into packages/mcp/src/data/symbology-options.json.

CI / Release

• CI (.github/workflows/ci.yml) — typecheck + build + test on Node 20 & 22 for every push and PR to main.
• Release (.github/workflows/release.yml) — pushing a v* tag publishes:
  • the npm package @cordfuse/barcoding-mcp (guards that the tag matches the package version), and
  • the Docker image ghcr.io/cordfuse/barcoding-mcp:<version> + :latest.

npm version patch -w @cordfuse/barcoding-mcp
git commit -am "release vX.Y.Z" && git tag vX.Y.Z && git push --follow-tags

Secrets: npm publish needs the org NPM_TOKEN (this repo must be on the org token's selected-repo allow-list). GHCR uses the built-in GITHUB_TOKEN (packages: write) — no secret required.

License

MIT