# doc.cheap – passport and ID OCR [Verified owner] [Health: Active]

**Category:** 🔎 Search & Data Extraction  
**Repository:** https://github.com/cheap-doc/ocr-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 955  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/doc-cheap-passport-and-id-ocr

## Description
Reads passports, ID cards and driver's licences from an image and returns the printed fields and MRZ results as structured JSON.

## Tools
Capabilities this server exposes over MCP:

- **scan_document** — Recognise a passport, national ID card or driver's licence from a photo or scan and return what is printed on it as structured JSON. Inputs: the image as image_base64 or image_url (https, on a public address); plus the optional expect_country, return_portrait, retain_hours, reference and idempotency_key. Output: a Scan object – meta (id, status, billed, confidence, timing), document (kind, issuing country, number, series, date of issue, date of expiry, whether it has expired and how many days are left), holder (given names, surname, date of birth, sex, nationality) – country codes are the document's own three-letter ICAO codes, each with a *_detail object giving the code as written, its ISO 3166-1 alpha-3 and alpha-2 and its category, fields (every field read off the printed page, each with its own confidence), mrz (whether the machine-readable zone checks out, why not when it does not, and its lines exactly as read), images, quality and authenticity – plus a one-line summary of the same result. Calls POST /v1/scans. Cost: it bills one credit ($0.01) only when a document is recognised; an unreadable image, an empty frame or an unsupported type costs nothing, and meta.billed says which happened. Without a key, the public sandbox key is used. It gives 10 free recognised documents per address in all, and at most 10 requests per address an hour, whatever their answer. Registering gives 100 free documents every month. Use test images only, never a real document. Use it whenever someone hands over an identity document and wants it read, transcribed, or checked against what they claim – a name, a document number, a date of birth or an expiry date.
- **check_balance** — Return how many credits are left on the account and what the current period has used: the balance, split into this month's free credits (100 every month, drawn first) and the paid credits, the credits spent, and the scan counters broken down by status (recognized, unreadable, no document found, unsupported document, rejected). Takes no arguments and calls GET /v1/usage; under the public sandbox key it answers without calling anything. One recognised document draws one credit, at $0.01; scans that recognised nothing are counted and never charged. Needs a real API key – under the public sandbox key there is no account behind the call, and the answer says so instead of reporting zeros that read like a balance. Use it before working through a batch of documents, or when a scan is refused for lack of credit.
- **search_docs** — Full-text search over the doc.cheap API documentation – endpoints, request options, every response field, the error codes and what to do about each, MRZ rules, retention and pricing. Takes a query and an optional limit (1 to 20, default 5), and answers with the matching sections: title, a snippet, and a link to the page. It reads a copy of the documentation shipped beside this server, so it makes no network call and works offline. Use it before guessing at a field name, an error code or a scan option – what it returns is the published contract rather than a recollection of it.
- **list_scans** — List the account's stored scans, most recent first, one page at a time. Inputs: the optional limit (1 to 100 rows, default 20) and cursor (the next_cursor of the previous page; omit it for the first page). Output: scans – one row per scan with id, status (recognized, unreadable, no_document_found, unsupported_document or rejected), billed, duration_ms, reference (your own string from the scan) and created_at – and next_cursor, which is null on the last page. A row holds no extracted data; call get_scan with its id for the full result. Calls GET /v1/scans; it never charges a credit. Only scans made with a live key under a non-zero retention window are stored for the account, and only until that window ends (retain_hours on the scan, or the account's history-retention setting, one year by default); a scan made with retain_hours 0 was never stored. A key reaches its own account's scans and no other account's. Under a sandbox key nothing can be read back: an account's own sk_sandbox_ key stores nothing, and the public key keeps every scan for one year, with a reduced thumbnail and the address it came from, where that key cannot read, list or delete it. Under the public sandbox key the answer is an empty list, given without calling the API. Errors: a cursor this API did not issue is refused (validation_failed); a key the API does not know is refused (unauthorized). Use it to find a scan made earlier – by its reference or its time – before reading or deleting it.
- **get_scan** — Fetch the full result of one stored scan by its id, as it was returned when the document was recognised. Input: scan_id – meta.id of a scan_document result, or id of a list_scans row. Output: the same Scan object scan_document returns (meta, document, holder, fields, mrz and the rest) plus a one-line summary, with two differences: the image crops are never stored, so every images slot is null, and quality reads not_checked. Calls GET /v1/scans/{id}; it never re-runs recognition and never charges a credit. Only scans made with a live key under a non-zero retention window are stored for the account, and only until that window ends (retain_hours on the scan, or the account's history-retention setting, one year by default); a scan made with retain_hours 0 was never stored. A key reaches its own account's scans and no other account's. Under a sandbox key nothing can be read back: an account's own sk_sandbox_ key stores nothing, and the public key keeps every scan for one year, with a reduced thumbnail and the address it came from, where that key cannot read, list or delete it. Errors: an id that is unknown, belongs to another account, was made with retain_hours 0 or has passed its window is refused as not_found – the cases are not told apart. Use it to read back a document recognised earlier instead of scanning the image again.
- **delete_scan** — Permanently delete one stored scan now, before its retention window would end. This cannot be undone: the stored result, its history row and its thumbnail are removed, and the scan can no longer be listed, fetched or replayed through its idempotency_key. The credit it drew is not refunded, and this period's usage counters still count it. Input: scan_id – meta.id of a scan_document result, or id of a list_scans row. Output: { id, deleted: true }. Calls DELETE /v1/scans/{id}. Only scans made with a live key under a non-zero retention window are stored for the account, and only until that window ends (retain_hours on the scan, or the account's history-retention setting, one year by default); a scan made with retain_hours 0 was never stored. A key reaches its own account's scans and no other account's. Under a sandbox key nothing can be read back: an account's own sk_sandbox_ key stores nothing, and the public key keeps every scan for one year, with a reduced thumbnail and the address it came from, where that key cannot read, list or delete it. Errors: an id that is unknown, belongs to another account, has passed its window or was already deleted is refused as not_found, and nothing is deleted. Use it when someone asks for a document's data to be removed; confirm the id with list_scans or get_scan first, because the deletion is final.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "doc-cheap-passport-and-id-ocr": {
    "command": "npx",
    "args": ["-y","@doc-cheap/mcp"]
  }
}
```

## Documentation

## What doc.cheap – passport and ID OCR does

Passport, national ID card, and driver's licence images can be submitted for OCR through the `scan_document` tool. The result is structured JSON containing document metadata, holder details, printed fields with individual confidence values, MRZ lines and validation status, image data, quality, authenticity, and a short summary. Document and country values include the document's own three-letter ICAO codes, with additional country details.

The server is a thin MCP client for the doc.cheap HTTP API and also includes a local copy of the doc.cheap API documentation. It does not keep an independent data store. Recognised documents cost one credit, priced at $0.01; unreadable images, empty frames, and unsupported documents are not charged.

## How it works

Run the package locally with `npx -y @doc-cheap/mcp`, or connect an MCP client to `https://mcp.doc.cheap/mcp` over Streamable HTTP. Local scans can use `image_base64`, `image_url`, or `image_path`; the hosted endpoint accepts `image_base64` and public HTTPS `image_url`, but cannot access files on the client machine.

A scan can include an expected country, portrait-return preference, retention period, caller reference, and idempotency key. Reusing an idempotency key returns the original result instead of creating and charging another recognition request. The public sandbox key works without configuration and provides limited free usage; a registered account provides monthly free credits.

## Setup and configuration

For a local process, set `DOC_CHEAP_API_KEY` to a live API key when account billing, usage, and stored scans are needed. Leaving it unset uses the public sandbox key. The package can be configured in Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI, Windsurf, and other MCP clients that support stdio. The hosted endpoint accepts a key through `X-Doc-Cheap-Api-Key` or a Bearer authorization header.

## Tools and capabilities

- `scan_document` recognises supported identity documents and returns structured OCR, MRZ, quality, authenticity, and document data.
- `check_balance` reports free and paid credits, spending, and scan-status counters.
- `search_docs` searches the bundled API documentation offline, including fields, options, errors, retention, MRZ rules, and pricing.
- `list_scans` paginates through stored scans using a cursor.
- `get_scan` retrieves the full result for a stored scan without rerunning recognition or charging a credit.
- `delete_scan` permanently removes a stored scan, its history row, and thumbnail.

## Limitations and notes

Use test images only; do not submit real identity documents. Stored scans are available only for live keys with a non-zero retention period and only until that period ends. A scan with `retain_hours` set to zero is not stored. Retrieved scans do not include image crops, and their quality is reported as `not_checked`.

Sandbox keys cannot provide account balances or read back stored scans. The public sandbox is rate-limited to 10 requests per address per hour and 10 recognised documents per address in total. Deleting a scan cannot be undone and does not refund its credit.

_Full upstream README: https://allmcps.com/mcp/doc-cheap-passport-and-id-ocr/readme_