Which integrations are available for this server?

Provides OCR capabilities using Yandex Vision API, allowing text extraction from images and PDFs with support for multiple recognition models and languages.

How do I use yandex-vision-ocr-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by chupre

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Hybrid

Yandex Vision OCR MCP

npm version npm downloads License: MIT Node Tests

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, via recognizeTextAsync + getRecognition polling.
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 ru and en (default ru; combine as ["ru","en"] for mixed text). Auto-detect is not supported by this endpoint.
Three output formats: text (default), markdown, or full json (the raw textAnnotation with blocks/lines/words/tables/entities).
Zero-touch error handling — API failures are returned as isError tool 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-mcp

Then wire it into your MCP client (see Configuration).

Configuration

The server reads credentials from environment variables:

Variable	Required	Description
`YANDEX_FOLDER_ID`	optional	Yandex Cloud folder ID. Only sent as `x-folder-id` when set — the API key already scopes requests, so you can usually leave this unset. If set, it must match the key's folder.
`YANDEX_API_KEY`	one of	API key (recommended for long-lived usage).
`YANDEX_IAM_TOKEN`	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
`page` (default)	Single-column printed text.
`page-column-sort`	Multi-column printed text.
`handwritten`	Mixed handwritten + printed text (Russian, English).
`table`	Tables (Russian, English).
`markdown`	Printed text, also returned as Markdown.
`math-markdown`	Math formulas, returned as Markdown with LaTeX (e.g. $a^2 + b^2$ ).

Tip: use format: "markdown" together with the markdown / math-markdown models to receive the model's Markdown output directly.

Tools

Both tools accept the same input shape:

Argument	Type	Default	Description
`path`	string	—	Local file to OCR. Provide this or `base64`.
`base64`	string	—	Base64 content (`data:` URIs accepted). Provide this or `path`.
`mimeType`	string	inferred	Explicit MIME type override.
`languages`	string[]	`["ru"]`	Recognition languages, selectable: `ru`, `en` (e.g. `["ru","en"]` for mixed).
`model`	string	`page`	Recognition model — see Models.
`format`	`text` \| `markdown` \| `json`	`text`	Output format.

Supported formats: JPEG, PNG, WEBP, HEIC, HEIF (images) and PDF. The mimeType sent to the API is derived automatically (you can pass a standard MIME type via mimeType if 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 OCR

Connect 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 command with ["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 build

Useful scripts:

Script	Description
`npm run build`	Compile TypeScript to `build/`.
`npm run typecheck`	Type-check without emitting.
`npm test`	Run the offline test suite.
`npm run dev`	Run the server from source (tsx).
`npm run inspector`	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.ts

Docker

docker build -t yandex-vision-ocr-mcp .
docker run --rm -i \
  -e YANDEX_FOLDER_ID=b1g... \
  -e YANDEX_API_KEY=... \
  yandex-vision-ocr-mcp

API coverage

This server targets the Yandex Cloud Vision OCR REST API (ocr.api.cloud.yandex.net/ocr/v1):

Route	Method	Used for
`/recognizeText`	POST	Synchronous recognition (`recognize_text`).
`/recognizeTextAsync`	POST	Start async recognition (`recognize_pdf`).
`/getRecognition`	GET	Poll for the async result.

Concepts: OCR overview · image · PDF · handwritten.

License

MIT

Available Tools

2 tools

recognize_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').

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	Absolute or relative path to a local file to read and OCR. Provide this OR 'base64'.
`base64`	No	Base64-encoded file content. May be a data URI ('data:<mime>;base64,...'). Provide this OR 'path'.
`mimeType`	No	Explicit MIME type override (e.g. 'image/jpeg'). Inferred from the file when omitted.
`languages`	No	Recognition languages (selectable). Use ['ru'], ['en'], or ['ru','en'] for mixed text. Defaults to ['ru']. This Yandex OCR endpoint does not support auto-detect.
`model`	No	Recognition model. 'page' (default): single-column printed text. 'page-column-sort': multi-column text. 'handwritten': mixed handwritten + printed (ru/en). 'table': tables (ru/en). 'markdown': printed text with Markdown output. 'math-markdown': math formulas (LaTeX in Markdown).	page
`format`	No	Output format. 'text' (default) returns recognized plain text. 'markdown' returns the model's Markdown output when available (markdown/math-markdown models), otherwise plain text. 'json' returns the full textAnnotation (blocks/lines/words/tables/markdown).	text

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description transparently discloses the asynchronous recognition process (recognizeTextAsync + getRecognition polling) and language limitations (no auto-detect). This is adequate disclosure for a non-destructive read operation, though rate limits or size constraints are not mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the core purpose and immediately following with usage guidance. Every sentence contributes essential information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, async polling, no output schema), the description covers the key behavioral aspects and parameter choices. It explains the async workflow and language limitations, but could have elaborated on the polling mechanism or return value format. Still, it is largely complete for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds minor value by summarizing model purposes (e.g., 'page-column-sort' for multi-column text) and the choice between path and base64, but these details are already present in the schema. No significant new information is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it recognizes text in a PDF document using Yandex Vision OCR, with details on async processing. This clearly distinguishes it from the sibling 'recognize_text' tool, which likely handles non-PDF formats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates use for PDFs and large files, providing context on when to apply it. While it doesn't explicitly list when not to use it or contrast with alternatives, the guidance is clear and sufficient for the intended use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	Absolute or relative path to a local file to read and OCR. Provide this OR 'base64'.
`base64`	No	Base64-encoded file content. May be a data URI ('data:<mime>;base64,...'). Provide this OR 'path'.
`mimeType`	No	Explicit MIME type override (e.g. 'image/jpeg'). Inferred from the file when omitted.
`languages`	No	Recognition languages (selectable). Use ['ru'], ['en'], or ['ru','en'] for mixed text. Defaults to ['ru']. This Yandex OCR endpoint does not support auto-detect.
`model`	No	Recognition model. 'page' (default): single-column printed text. 'page-column-sort': multi-column text. 'handwritten': mixed handwritten + printed (ru/en). 'table': tables (ru/en). 'markdown': printed text with Markdown output. 'math-markdown': math formulas (LaTeX in Markdown).	page
`format`	No	Output format. 'text' (default) returns recognized plain text. 'markdown' returns the model's Markdown output when available (markdown/math-markdown models), otherwise plain text. 'json' returns the full textAnnotation (blocks/lines/words/tables/markdown).	text

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses synchronous operation, supported MIME types, model behaviors, and language limitations (no auto-detect, only ru/en). It could mention error handling or response size, but overall transparency is good.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient paragraph of 3-4 sentences, front-loaded with core purpose. Every sentence adds value: format support, model options, input alternatives, and sibling tool reference. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters, 100% schema coverage, and no output schema, the description covers input sources, model options, language limits, and sibling tool. It omits error handling and output format details (but format parameter covers that). Adequate for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds context about model use cases and mutual exclusivity of path/base64, but does not significantly deepen understanding beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: recognize text in images or single-page PDFs using Yandex Vision OCR (synchronous). It specifies supported formats and distinguishes from the sibling tool 'recognize_pdf' by noting multi-page PDFs should use that tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool vs 'recognize_pdf' for multi-page/large PDFs. It also explains input options (path vs base64), model selection, and output formats, giving clear usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

2 tool updatesv0.3.0Jun 23, 2026
- First observedrecognize_pdf
- First observedrecognize_text

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

Scored 2026-06-23 20:30 across 2 tools

Disambiguation5/5

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.

Naming Consistency4/5

Both tools follow the 'recognize_' prefix pattern with clear suffixes ('pdf' and 'text'), making them predictable and self-explanatory.

Tool Count4/5

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.

Completeness4/5

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

ActivityStale

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

ocr A
com.auto-reader
Arabic-first OCR, translation and document extraction. First call mints a free trial key.
Image & Video Processing Language Translation AI & Machine Learning
72
APICK OCR A
app.apick
OCR for images and Korean ID documents
Image & Video Processing AI & Machine Learning Security
611
FactScan AI
app.factscanai
OCR and document understanding: extract text from images, then summarize or translate it.
Image & Video Processing Text Summarization Language Translation
1
mindee A
io.usefulapi
Turn PDFs and images into typed fields — invoices, receipts, IDs and custom models — via Mindee OCR.
AI & Machine Learning Data Platforms
42

Related MCP Servers

macOS Native OCR MCP Server
Image & Video Processing Multimedia Processing Developer Tools
wenjiazhu
F
license
Not graded
quality
Not graded
maintenance
Provides 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.
Updated 8 months ago (2026-01-23 12:48 UTC)
1
-
yandex-searchapi-mcp
Search Marketing
shufl9dka
A
license
A
quality
D
maintenance
Provides tools for web, image, generative search, and Wordstat keyword statistics via Yandex Search API.
Updated 4 months ago (2026-05-07 00:10 UTC)
7
4
1
MIT
Vision-OCR-MCP
Image & Video Processing AI & Machine Learning
AliceAuto
F
license
Not graded
quality
D
maintenance
Enables OCR on images and PDFs, including full-page OCR, region OCR by description or bounding box, and caching with summary capabilities.
Updated 5 months ago (2026-04-02 07:20 UTC)
-
Tesseract OCR MCP Server
Image & Video Processing AI & Machine Learning
daboatan
F
license
Not graded
quality
C
maintenance
Enables AI assistants and applications to perform optical character recognition (OCR) from images via stdin/stdout streams or REST API endpoints.
Updated 2 months ago (2026-07-12 10:15 UTC)
-

Yandex Vision OCR MCP

Features

Prerequisites

Quick start

Configuration

Models

Tools

Example result (text format)

Connect to opencode

Connect to Claude Desktop / Cursor / Cline

Local development

Testing

Docker

API coverage

License

Available Tools

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

macOS Native OCR MCP Server

yandex-searchapi-mcp

Vision-OCR-MCP

Tesseract OCR MCP Server

Example result (`text` format)