Skip to main content

libscanner MCP server

An MCP server that lets Claude, ChatGPT and coding agents read and create barcodes through the libscanner API:

Tool What it does
decode_code Reads DataMatrix, QR Code, Code 128, GS1-128 and EAN/UPC codes in a JPEG or PNG image. Returns the exact text of every code (the GS separator is the real character U+001D), its symbology and corners, the GS1 fields and a structure check
parse_gs1 Parses a code string as GS1 and checks its structure without an image: application identifiers, the GTIN check digit, Chestny ZNAK («Честный знак») verification fields 91/92/93, a missing GS separator, an expired date
generate_code Creates a DataMatrix image (PNG), optionally validated as GS1 DataMatrix or as a Chestny ZNAK marking code, or a QR Code for links and text
get_usage The plan of the API key and the remaining limits

Documentation: https://libscanner.com/docs/api/?lang=mcp.

The server contains no recognition logic. Every tool is one call to https://api.libscanner.com/v1 (OpenAPI); the readers are the same ones that are sold as the dmr and unir libraries.

The tools check the format of a marking code. They do not query the status of an item in a government marking system.

API key

Create a free key at https://libscanner.com/cabinet/api (300 requests a month, 30 a day). Paid plans and limits are on the API page.

Local server (stdio)

The local server runs on your machine, so decode_code can read an image file (image_path) and generate_code can save the PNG (output_path). This is the way to use it from coding agents.

LIBSCANNER_API_KEY=lsk_live_... uvx libscanner-mcp

Claude Code

claude mcp add libscanner --env LIBSCANNER_API_KEY=lsk_live_... -- uvx libscanner-mcp

Claude Desktop, Cursor (claude_desktop_config.json, .cursor/mcp.json)

{
  "mcpServers": {
    "libscanner": {
      "command": "uvx",
      "args": ["libscanner-mcp"],
      "env": { "LIBSCANNER_API_KEY": "lsk_live_..." }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "libscanner": {
      "type": "stdio",
      "command": "uvx",
      "args": ["libscanner-mcp"],
      "env": { "LIBSCANNER_API_KEY": "${input:libscanner-key}" }
    }
  },
  "inputs": [{ "id": "libscanner-key", "type": "promptString", "description": "libscanner API key", "password": true }]
}

Safety of the file parameters:

  • image_path is sent to the API only if the file is a JPEG or PNG (checked by its signature) of at most 8 MB. Any other file is refused before anything leaves the machine.
  • output_path must end in .png, must not exist yet (nothing is overwritten) and its folder must exist.
  • Both must be paths on this machine: network paths (\\host\share\…, //host/…) are refused before they are touched — on Windows merely opening one sends the user's NTLM hash to that host.

Cloud server (Streamable HTTP)

https://mcp.libscanner.com/mcp — nothing to install. The API key travels in a header:

claude mcp add --transport http libscanner https://mcp.libscanner.com/mcp --header "Authorization: Bearer lsk_live_..."
{
  "mcpServers": {
    "libscanner": {
      "url": "https://mcp.libscanner.com/mcp",
      "headers": { "Authorization": "Bearer lsk_live_..." }
    }
  }
}

Without a key parse_gs1 and generate_code still work, with a small daily limit per address — enough to try the server.

The cloud server cannot see files attached to a chat: decode_code takes a public link (image_url). image_base64 exists only for tiny images (up to 64 KB), because a model writes tool arguments character by character.

Images and storage

JPEG and PNG up to 8 MB, 4096 px on a side and 16 megapixels. On paid plans images are not stored. On the free plan images in which no code was read are kept for up to a year to improve recognition. Decoded codes are never stored. Details: https://libscanner.com/api/#storage.

Running the cloud flavour yourself

pip install "libscanner-mcp[cloud]"
LIBSCANNER_MCP_ALLOWED_HOSTS=mcp.example.com libscanner-mcp --http --host 0.0.0.0 --port 8000
Variable Meaning
LIBSCANNER_API_URL API address, https://api.libscanner.com by default
LIBSCANNER_API_KEY local server: the key of the user
LIBSCANNER_MCP_ALLOWED_HOSTS cloud: public host names of the server, comma-separated. Requests under any other Host are rejected (DNS rebinding protection)
LIBSCANNER_MCP_ANONYMOUS_API_KEY cloud: the key that pays for calls without sign-in (parse_gs1, generate_code). Not set — such calls are refused
LIBSCANNER_MCP_ANONYMOUS_DAILY_LIMIT cloud: calls without sign-in per client address (IPv6: per /64) a day, 20 by default
LIBSCANNER_MCP_ANONYMOUS_NETWORK_DAILY_LIMIT cloud: the same per network — IPv4 /24, IPv6 /48 — 200 by default
LIBSCANNER_MCP_ANONYMOUS_TOTAL_DAILY_LIMIT cloud: all calls without sign-in a day (except the shared counter below), 5000 by default
LIBSCANNER_MCP_SHARED_DAILY_LIMIT cloud: one shared daily counter for clients whose requests come from the provider's addresses (claude.ai), 2000 by default

The reverse proxy in front of the server must pass the client address in X-Real-IP, overwriting whatever the client sent: the limit of calls without sign-in is counted by it. A call without sign-in that the API did not serve — the rate or plan limit of the service key, a failure on the API side — is not counted. The service key needs the generate scope only (parse_gs1 needs none); give it a plan of its own, since the per-key rate limit of the API applies to all calls without sign-in together.

The cloud server logs warnings and the access log only (address, path, status): at the INFO level the SDK would log the text of failed tool calls, which may quote the caller's data.

Development

uv venv && uv pip install -e ".[cloud,dev]"
pytest

License

MIT. Chestny ZNAK («Честный знак») and GS1 are trademarks of their respective owners.

Metadata

Release files for libscanner-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for libscanner-mcp 0.1.0
File Size Uploaded Provenance Actions
libscanner_mcp-0.1.0.tar.gz 23.8 kB Without provenance Details for libscanner_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for libscanner-mcp 0.1.0
File Interpreter ABI Platform Actions
libscanner_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for libscanner_mcp-0.1.0-py3-none-any.whl

Total release size: 42.7 kB

Release files / libscanner_mcp-0.1.0.tar.gz

Download URL libscanner_mcp-0.1.0.tar.gz
Size 23.8 kB
Tags Source
SHA-256 checksum
How to use checksums
f43910c5864c1c179a1d2571d6b619b852231dacaacd26bbd9c0666e881158f1
BLAKE2b-256 checksum
How to use checksums
c2e9792a1c7e7d201ed9dc02c4df13fe06e097bfae4751cff973ee5d208a1a81
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / libscanner_mcp-0.1.0-py3-none-any.whl

Download URL libscanner_mcp-0.1.0-py3-none-any.whl
Size 19.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ff36ea1b86e9ef9dd13c667be3082eeae6752259f038589568c52509a0dd1286
BLAKE2b-256 checksum
How to use checksums
dde589b067e4a59cfdd786ec1025cf3bcf272462f8f42d2cd5e8da64e93e5315
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for libscanner-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page