barcoding-mcp

npm

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 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