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_pathis 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_pathmust 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.