Metadata-Version: 2.5
Name: libscanner-mcp
Version: 0.1.0
Summary: MCP server for libscanner: read and generate DataMatrix, QR and barcodes, parse GS1 and Chestny ZNAK marking codes
Project-URL: Homepage, https://libscanner.com/api/
Project-URL: Documentation, https://libscanner.com/docs/api/?lang=mcp
Author-email: libscanner <libscanner@yandex.com>
License-Expression: MIT
License-File: LICENSE
Keywords: barcode,chestny-znak,datamatrix,gs1,mcp,model-context-protocol,qr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: Capture :: Scanners
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: httpx2<3,>=2.16
Requires-Dist: mcp<3,>=2.3
Provides-Extra: cloud
Requires-Dist: mcp[cli]<3,>=2.3; extra == 'cloud'
Provides-Extra: dev
Requires-Dist: anyio>=4; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# libscanner MCP server

<!-- mcp-name: com.libscanner/barcode -->

An [MCP](https://modelcontextprotocol.io) server that lets Claude, ChatGPT and coding agents read and
create barcodes through the [libscanner API](https://libscanner.com/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](https://api.libscanner.com/openapi.json)); the readers are the same ones that are sold as the
[dmr and unir libraries](https://libscanner.com/).

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](https://libscanner.com/api/#pricing).

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

```sh
LIBSCANNER_API_KEY=lsk_live_... uvx libscanner-mcp
```

**Claude Code**

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

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

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

**VS Code** (`.vscode/mcp.json`)

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

```sh
claude mcp add --transport http libscanner https://mcp.libscanner.com/mcp --header "Authorization: Bearer lsk_live_..."
```

```json
{
  "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

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

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

## License

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