yandex-vision-ocr-mcp
Provides OCR capabilities using Yandex Vision API, allowing text extraction from images and PDFs with support for multiple recognition models and languages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yandex-vision-ocr-mcp extract text from receipt.png"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Yandex Vision OCR MCP
A Model Context Protocol (MCP) server that exposes Yandex Vision OCR as tools, so any MCP-compatible client — opencode, Claude Desktop, Cursor, Cline — can extract text from images and PDFs.
Features
recognize_text— synchronous OCR for images (JPEG/PNG/WEBP/HEIC/HEIF) and single-page PDFs.recognize_pdf— asynchronous OCR for PDFs (single- or multi-page) and large files, viarecognizeTextAsync+getRecognitionpolling.Recognition models — printed text, multi-column, handwritten, tables, Markdown, and math formulas (LaTeX), selectable per call.
Accepts a local file path or raw base64 content.
Recognition languages selectable between
ruanden(defaultru; combine as["ru","en"]for mixed text). Auto-detect is not supported by this endpoint.Three output formats:
text(default),markdown, or fulljson(the rawtextAnnotationwith blocks/lines/words/tables/entities).Zero-touch error handling — API failures are returned as
isErrortool results, never crashes.Lazy credentials — the server boots and lists tools even before
YANDEX_*env vars are set, surfacing a clear error only on the first call.
Related MCP server: yandex-searchapi-mcp
Prerequisites
Node.js ≥ 20.
A Yandex Cloud account with the Vision/OCR API enabled.
A folder ID + either an API key (recommended) or an IAM token. See the authentication docs.
Quick start
# Run directly with npx (no install needed)
npx -y yandex-vision-ocr-mcpThen wire it into your MCP client (see Configuration).
Configuration
The server reads credentials from environment variables:
Variable | Required | Description |
| optional | Yandex Cloud folder ID. Only sent as |
| one of | API key (recommended for long-lived usage). |
| one of | Short-lived IAM token (~12h). Use instead of an API key. |
See .env.example for a template.
Models
Pass model to any tool to pick the recognition behaviour:
Model | Best for |
| Single-column printed text. |
| Multi-column printed text. |
| Mixed handwritten + printed text (Russian, English). |
| Tables (Russian, English). |
| Printed text, also returned as Markdown. |
| Math formulas, returned as Markdown with LaTeX (e.g. |
Tip: use
format: "markdown"together with themarkdown/math-markdownmodels to receive the model's Markdown output directly.
Tools
Both tools accept the same input shape:
Argument | Type | Default | Description |
| string | — | Local file to OCR. Provide this or |
| string | — | Base64 content ( |
| string | inferred | Explicit MIME type override. |
| string[] |
| Recognition languages, selectable: |
| string |
| Recognition model — see Models. |
|
|
| Output format. |
Supported formats: JPEG, PNG, WEBP, HEIC, HEIF (images) and PDF. The
mimeTypesent to the API is derived automatically (you can pass a standard MIME type viamimeTypeif needed). BMP/TIFF are not supported by the service.
recognize_text— synchronous. Best for images and single-page PDFs.recognize_pdf— asynchronous (submit + poll). Best for multi-page PDFs and large files. Requires the input to be a PDF.
Example result (text format)
Hello World
Yandex OCRConnect to opencode
Add the server to your opencode.json under mcp:
{
"mcp": {
"yandex-vision-ocr": {
"type": "local",
"command": ["npx", "-y", "yandex-vision-ocr-mcp@latest"],
"enabled": true,
"environment": {
"YANDEX_FOLDER_ID": "b1g...",
"YANDEX_API_KEY": "your-api-key"
}
}
}
}If you cloned the repo instead, replace the
commandwith["node", "/absolute/path/to/yandex-vision-ocr-mcp/build/index.js"].
Connect to Claude Desktop / Cursor / Cline
{
"mcpServers": {
"yandex-vision-ocr": {
"command": "npx",
"args": ["-y", "yandex-vision-ocr-mcp@latest"],
"env": {
"YANDEX_FOLDER_ID": "b1g...",
"YANDEX_API_KEY": "your-api-key"
}
}
}
}{
"mcpServers": {
"yandex-vision-ocr": {
"command": "npx",
"args": ["-y", "yandex-vision-ocr-mcp@latest"],
"env": {
"YANDEX_FOLDER_ID": "b1g...",
"YANDEX_API_KEY": "your-api-key"
}
}
}
}Local development
git clone https://github.com/chupre/yandex-vision-ocr-mcp.git
cd yandex-vision-ocr-mcp
npm install
npm run build # type-check + compile to build/
npm test # run the vitest suite
npm run dev # run the server from source via tsx
npm run inspector # open the MCP Inspector UI against the buildUseful scripts:
Script | Description |
| Compile TypeScript to |
| Type-check without emitting. |
| Run the offline test suite. |
| Run the server from source (tsx). |
| Launch the MCP Inspector for manual testing. |
Testing
The offline suite covers input handling, MIME inference, response formatting, the HTTP client (via a fake transport, no network), tool wiring, and a full MCP round-trip over an in-memory transport.
Live integration tests hit the real Yandex OCR API and are skipped unless credentials and sample files are provided:
YANDEX_FOLDER_ID=... YANDEX_API_KEY=... \
YOCR_LIVE_IMAGE=./sample.png \
YOCR_LIVE_PDF=./sample.pdf \
npx vitest run tests/live.test.tsDocker
docker build -t yandex-vision-ocr-mcp .
docker run --rm -i \
-e YANDEX_FOLDER_ID=b1g... \
-e YANDEX_API_KEY=... \
yandex-vision-ocr-mcpAPI coverage
This server targets the Yandex Cloud Vision OCR REST API
(ocr.api.cloud.yandex.net/ocr/v1):
Route | Method | Used for |
| POST | Synchronous recognition ( |
| POST | Start async recognition ( |
| GET | Poll for the async result. |
Concepts: OCR overview · image · PDF · handwritten.
License
Available Tools
2 toolsrecognize_pdfA
Recognize text in a PDF document (single or multi-page) using Yandex Vision OCR via asynchronous recognition (recognizeTextAsync + getRecognition polling). Use this for PDFs and large files. Provide a local file 'path' or 'base64' content, and pick a 'model' (default 'page').
Inputs: path, base64, mimeType, languages, +2 more.
recognize_textA
Recognize text in an image (JPEG/PNG) or a single-page PDF using Yandex Vision OCR (synchronous). Picks the recognition model via 'model' (default 'page' for printed text; 'handwritten', 'table', 'markdown', etc.). Provide a local file 'path' or 'base64' content. For multi-page/large PDFs, use recognize_pdf instead.
Inputs: path, base64, mimeType, languages, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one for images and single-page PDFs (synchronous), the other for multi-page/large PDFs (asynchronous). No overlap in functionality.
Both tools follow the 'recognize_' prefix pattern with clear suffixes ('pdf' and 'text'), making them predictable and self-explanatory.
Two tools is minimal but appropriate for a focused OCR server. It covers the core distinction between image/single-page and multi-page PDF processing without unnecessary complexity.
The tool surface covers the essential OCR use cases: image and PDF text recognition. The model parameter handles handwritten, table, and markdown, so no major gaps.
Maintenance
Related MCP Connectors
OCR text from images and scanned PDFs; pay-per-event via your Apify account.
Arabic-first OCR, translation and document extraction. First call mints a free trial key.
Hosted OCRmyPDF: add a searchable text layer to scanned PDFs and images, returned as PDF/A.
OCR for images and Korean ID documents
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceProvides offline, high-accuracy OCR capabilities for images and PDFs using macOS's built-in Vision framework. Supports multi-language text extraction with intelligent block aggregation for tables and paragraphs, outputting structured JSON data suitable for document reconstruction.1-
- AlicenseAqualityDmaintenanceProvides tools for web, image, generative search, and Wordstat keyword statistics via Yandex Search API.71MIT
- FlicenseNot gradedqualityDmaintenanceEnables OCR on images and PDFs, including full-page OCR, region OCR by description or bounding box, and caching with summary capabilities.-
- FlicenseNot gradedqualityDmaintenanceProvides OCR capabilities for images and PDFs using Mistral AI's OCR API, supporting both local files and URLs with output in markdown or JSON format.-