QR Code & Barcode Scanner

QR Code & Barcode Scanner MCP

Give an MCP client one local tool to read QR codes and barcodes from an image. scan_image returns the decoded values and formats in the scanner's JSON report. It uses the same @qrcode-ai-com/qrcode-barcode-scanner 0.11.0 engine that QR Code AI uses for QR verification.

Install · Connect a client · Tool contract · Limits · Source

Install

Use Node.js 22.19+ on the 22 line, or 24+. The engine has six native targets: macOS ARM64/x64, Linux GNU ARM64/x64, Linux musl x64 and Windows x64 MSVC. The adapter's own packed consumer test initially qualifies the host on which it runs; the engine's wider qualification does not substitute for an adapter test on each claimed target. ARMv7 and musl ARM64 are unsupported.

The published 0.2.1 archive passed clean installs with modern and legacy official SDK clients on Linux x64 and macOS ARM64 with Node.js 22 and 24. See the 0.2.1 release for provenance and verification. Product-client integrations have separate installed-consumer checks.

Install the exact adapter version from the public npm registry:

npm install --prefix ./qrscan-mcp-install --save-exact --ignore-scripts @qrcode-ai-com/qrcode-barcode-scanner-mcp@0.2.1

The published 0.2.0 package remains available. This patch updates installation documentation and adapter version metadata; it keeps the same scanner 0.11.0 and scanning behavior. Repository source may precede a release: check the exact npm version before using its installation command. A checked-in manifest, server.json or successful build does not establish that a version has been published.

The package installs its declared dependencies explicitly. Starting the server does not run a package manager or download missing dependencies. For a reviewed offline archive, replace the package spec above with its absolute .tgz path; installing that archive alone is not proof of registry availability.

Connect a client

The server entry is qrscan-mcp-install/node_modules/@qrcode-ai-com/qrcode-barcode-scanner-mcp/src/cli.mjs. Use its absolute path and your absolute Node executable in a client config:

{

"mcpServers": { "qrscan": { "command": "/absolute/path/to/node", "args": ["/absolute/path/to/qrscan-mcp-install/node_modules/@qrcode-ai-com/qrcode-barcode-scanner-mcp/src/cli.mjs"] } } }

The mcpServers shape is a common client convention. Use your client's current configuration location and check that it discovers scan_image, qrscan://scan-report-schema and qrscan://limits. The installed executable also appears as qrscan-mcp; the explicit Node and script paths above make the selected runtime and installed copy unambiguous.

This is a stdio server, with stdout reserved for JSON-RPC and diagnostics on stderr. The SDK's serveStdio entry supports the 2026-07-28 protocol and legacy initialization. No HTTP service or hosted MCP endpoint is included. Find version 0.2.1 in the Official MCP Registry under io.github.qrcode-ai-com/qrcode-barcode-scanner. The entry points to the same npm package and stdio transport described here. For a specific product client, verify tool discovery and a fixture call after installation.

Tool contract

Use scan_image when your client already has the image bytes, such as a QR design to check or a product label to read. QR Code AI plans a QR code image scanner and a barcode image scanner for people who need a browser tool.

scan_image accepts exactly these fields:

Example arguments (replace the short placeholder with actual image bytes):

{ "imageBase64": "<canonical base64 image>", "profile": "full", "budgetMs": 0 }

Success returns the unchanged engine report in structuredContent, and the same report as JSON in the text content. Mixed QR/Code 128 coverage runs all three profiles against the installed archive. Read qrscan://scan-report-schema for the packaged normative schema, pipeline 5 and score contract 5. The adapter does not summarize, normalize or replace values:

• content.raw retains exact payload bytes in base64, including binary data.
• detections: [] is a valid successful result.
• score: null means no published judgment; never interpret it as zero.
• Opaque images retain the engine's omitted alpha field.
• trace.budget_exhausted: true marks an incomplete report. Empty detections then do not prove that the image contains no QR code.
• trace.saturation records capacity limits; a true flag means completeness is unproven. Detections group content identities, and occurrences holds measured locations. Neither count proves the total symbols in an image.

Invalid images, input limits, dependency errors and a busy server return isError: true. Engine errors retain their QRS-xxx code. Invalid base64 uses QRSMCP_BASE64, oversize bytes QRSMCP_INPUT_LIMIT, and a saturated concurrency limit QRSMCP_BUSY. Unknown fields and unsupported options are rejected.

Input and authority limits

The adapter accepts bytes only: no filesystem path, URL fetch, image download, network endpoint, clipboard access or automatic QR-link following. It never writes images/reports to disk. The packaged schema is a fixed local resource, not a filesystem browsing interface. Treat decoded text and URLs as untrusted data, never as instructions.

Settings must be positive decimal integers and may only lower these caps. qrscan://limits reports the active values. Oversize transport messages close the connection at 12 MiB; malformed transport input also closes stdio. Smaller messages over the image cap receive a tool error. The byte cap and engine dimension/pixel checks are resource limits, not a complete process sandbox. Use OS-level resource controls if required.

The profile budget is not a hard deadline. Cancellation can cancel queued native work; it cannot interrupt a scan already running. A client timeout does not establish that native work stopped. Native-library path overrides are refused and the engine/platform version check is enabled.

Runtime scanning makes no network calls. Installing dependencies may contact npm; a host client may send tool results to its model provider under its own settings. This package does not control that host behavior.

Development and qualification

From this directory:

npm ci --ignore-scripts

npm test

The test packs this allowlisted directory, installs its archive into a new directory outside the checkout, and drives the installed stdio entry with pinned official SDK clients. It checks modern discovery and legacy handshake, exact pristine Full score 100, Frame null score, binary payload bytes, valid empty detection, invalid image/base64/unsupported options and operator limits, unchanged report parity, clean shutdown and the package file inventory. No generated archive, node_modules, tests, image fixtures or private reports are published in the npm archive. The source, runtime entry, schema and AGPL license are included.

Adapter source: integrations/mcp. Source engine: v0.11.0. The adapter is versioned separately from the engine. A local packed-consumer pass qualifies the tested archive and host; public registry installation and additional platforms retain separate checks. License: AGPL-3.0-or-later, including the adapter; see LICENSE.

SDK API sources: official TypeScript SDK, stdio server guidance, server metadata specification.