Provides OCR (Optical Character Recognition) capabilities using PaddleOCR to recognize and extract text from images, supporting both file path and base64 input with structured results including text content, confidence scores, and bounding box positions.
Click on "Install 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., "@OCR MCP Service recognize_image_paddleocr: extract text from this receipt image"
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.
基于
FastMCP与PaddleOCR的最小化本地 OCR MCP 服务，只保留stdio -> ocr_recognize -> PaddleOCR -> 统一响应 envelope这一条主路径，适合本地 IDE、Agent 和 MCP Client 直接接入。
环境要求
Python 3.10+
uv
PyPI 发布状态
已发布到 PyPI：local-ocr-mcp==0.2.0
1. 直接用 uvx 运行
uvx --from "local-ocr-mcp[paddleocr]==0.2.0" local-ocr-mcp适合直接接入 MCP 客户端，不需要手动创建虚拟环境。
首次运行会安装 paddleocr、paddlepaddle、opencv 等依赖，时间可能明显更长；后续复用缓存后会快很多。
如果你希望始终跟随最新发布版本，也可以省略固定版本号：
uvx --from "local-ocr-mcp[paddleocr]" local-ocr-mcp2. 本地开发运行
git clone <repository-url>
cd local-ocr-mcp
uv sync --extra dev --extra paddleocr
uv run python -m local_ocr_mcp3. MCP 客户端配置示例
{
"mcpServers": {
"local-ocr-mcp": {
"command": "uvx",
"args": ["--from", "local-ocr-mcp[paddleocr]==0.2.0", "local-ocr-mcp"]
}
}
}📖 仓库里也保留了一份同步后的配置样例 → mcp_config.json
Related MCP server: GLM OCR MCP Server
特性 | 说明 |
单路径主链路 | 只保留 |
最小工具面 | 对外只暴露 |
统一响应契约 | 所有工具统一返回 |
固定输入模型 | 当前只接受本地图片路径 |
稳定错误语义 | 用固定错误码暴露常见失败路径，便于客户端编排与恢复 |
低认知负担 | 不保留多引擎、analysis、progress、heartbeat、registry/factory 等扩展层 |
Python 3.10+ / uv - 运行时与依赖管理
FastMCP - MCP 服务框架
PaddleOCR - 固定 OCR 引擎
Pillow - 图片合法性校验
pytest - 最小契约测试
┌──────────────────────────────────────────────────────┐
│ MCP Client / IDE / Agent │
├──────────────────────────────────────────────────────┤
│ stdio transport │
├──────────────────────────────────────────────────────┤
│ FastMCP Tools: ocr_recognize / health_check │
├──────────────────────────────────────────────────────┤
│ RecognitionService HealthService │
├──────────────────────────────────────────────────────┤
│ PaddleOCREngine │
├──────────────────────────────────────────────────────┤
│ PaddleOCR / Filesystem / Image Validation │
└──────────────────────────────────────────────────────┘当前实现刻意保持单向依赖和短链路：
CLI 只负责启动 stdio
Tool 层只负责暴露 MCP 接口
Service 层负责校验输入并整形成统一 envelope
Engine 层只负责调用 PaddleOCR 并归一化结果
工具 | 说明 |
| 识别本地图片并返回统一 OCR 结果 |
| 返回轻量健康状态、运行时版本和启动时长 |
ocr_recognize 请求示例{
"image": {
"path": "./example.png"
}
}ocr_recognize 输入约束image 必须是对象
image.path 必须是非空字符串
当前只允许 image.path
相对路径会按服务进程当前工作目录解析为绝对路径
ocr_recognize 成功响应示例{
"status": "ok",
"data": {
"text": "示例文本",
"boxes": [
{"x1": 0.0, "y1": 0.0, "x2": 120.0, "y2": 32.0}
],
"confidence": 0.98,
"engine": "paddleocr",
"processing_ms": 143
},
"error": null,
"meta": {
"timestamp": "2026-03-14T00:00:00+00:00",
"runtime_version": "0.2.0",
"request_id": "8c4c9d5c-6b4d-4f1f-b6df-4ff80e3ff6b6",
"resolved_engine": "paddleocr",
"resolved_image_path": "/abs/path/example.png"
}
}ocr_health_check 响应示例{
"status": "ok",
"data": {
"status": "healthy",
"uptime_ms": 1234,
"transport": "stdio",
"runtime_version": "0.2.0"
},
"error": null,
"meta": {
"timestamp": "2026-03-14T00:00:00+00:00",
"runtime_version": "0.2.0"
}
}{
"status": "error",
"data": null,
"error": {
"code": "file_not_found|invalid_image|engine_not_available|internal_error",
"message": "具体错误信息",
"retryable": false
},
"meta": {
"timestamp": "...",
"runtime_version": "0.2.0",
"request_id": "...",
"resolved_engine": "paddleocr"
}
}file_not_found：image.path 指向的文件不存在
invalid_image：请求结构不合法，或文件存在但不是有效图片
engine_not_available：PaddleOCR 未安装或初始化失败
internal_error：识别链路内部出现未归类异常
只支持 stdio
只支持 PaddleOCR
不会自动切换引擎
不支持 streamable-http
不支持 analysis、progress、heartbeat
不支持 URL、base64、上传流等非文件输入
内部固定使用 PaddleOCR，但对其 Python API 保留最小兼容：
优先走较新的 predict()
如果安装版本只支持旧接口，则回退到 ocr()
对外继续返回统一响应结构
变量 | 说明 | 默认值 |
| PaddleOCR 初始化语言 |
|
| 日志级别 |
|
示例：
PADDLEOCR_LANG=ch LOG_LEVEL=INFO uv run python -m local_ocr_mcp当前 scripts/ 目录只保留和最小实现一致的两个脚本：
uv run python scripts/list_tools.py
uv run python scripts/recognize_image.py path/to/image.png --json
📖 详细说明 → scripts/README.md
常用命令：
uv run python -m pytest -q
uv run python -m local_ocr_mcp --help
uv run python scripts/list_tools.py
uv run python scripts/recognize_image.py path/to/image.png --jsonCI 当前只覆盖最小必需验证：
编译检查
单元测试
CLI --help
stdio 启动烟测
因为它在等待 MCP 客户端通过 stdio 调用工具。这是正常行为。
engine_not_available？通常说明 PaddleOCR 或底层依赖没有正确安装。优先重新同步依赖：
uv sync --extra paddleocr如果你是通过 uvx 启动，确认命令里包含：
uvx --from local-ocr-mcp[paddleocr]==0.2.0 local-ocr-mcp如果你故意选择跟随最新版本，也可以使用不带版本号的形式：
uvx --from local-ocr-mcp[paddleocr] local-ocr-mcpinvalid_image？常见原因：
请求里没有 image.path
image.path 不是字符串
文件存在，但不是合法图片
相对路径是相对于服务进程当前工作目录解析的。最稳妥的做法是直接传绝对路径。
因为当前版本明确选择“核心最小化”路线，只保留本地 OCR 主链路，不为未来扩展提前保留复杂结构。
最后更新: 2026-03-14
License: MIT
Return lightweight health status for the stdio runtime.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates the tool 'returns' health status, implying a read operation, but fails to explicitly state whether it is safe, idempotent, or has any side effects. The mention of 'lightweight' hints at performance characteristics but lacks detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of a single, efficient sentence of seven words that immediately communicates the tool's function. There is no redundant or extraneous information; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters) and the existence of an output schema (per context signals), the description is appropriately minimal. It adequately covers what the tool does without needing to elaborate on return values, though it could explicitly mention this is a non-destructive diagnostic operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage. By the baseline rule for zero-parameter tools, this earns a 4. No additional parameter context is needed or provided in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a 'lightweight health status' for the 'stdio runtime', providing specific verb and resource information. It effectively distinguishes from sibling 'ocr_recognize' by indicating this is a health diagnostic rather than OCR functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, or under what circumstances it should be invoked (e.g., before operations, for monitoring, etc.). No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recognize text from one local image path via PaddleOCR.
| Name | Required | Description | Default |
|---|---|---|---|
| image | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. While 'Recognize' implies a read-only operation, the description fails to disclose error behaviors (e.g., failed OCR), whether temporary files are created, or PaddleOCR-specific requirements like language support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with zero waste. Each clause provides distinct value: the action (recognize text), the input constraint (local image path), and the technology context (PaddleOCR).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a single-parameter tool with an output schema (return values need not be described), but the description leaves ambiguity about the 'image' object structure and lacks behavioral safety context required given the absence of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by clarifying that the 'image' parameter expects a 'local image path,' adding critical semantic meaning absent from the schema. However, it doesn't explain the object structure despite the schema defining it as an object with additionalProperties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Recognize'), target resource ('text'), source ('one local image path'), and implementation ('PaddleOCR'). It clearly distinguishes from the sibling 'ocr_health_check' by focusing on text extraction rather than service status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'one local image path' implies the tool is intended for local file OCR, but there is no explicit guidance on when to use this versus the health check, supported image formats, or file size constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The two tools have completely distinct purposes: one is for system health monitoring and the other is for the core OCR functionality. There is no overlap or ambiguity between checking runtime status and performing text recognition from images.
Both tools follow a consistent 'ocr_' prefix pattern with clear, descriptive names (ocr_health_check and ocr_recognize). The naming convention is uniform and predictable throughout the set.
With only 2 tools, this server feels significantly under-scoped for an OCR service. While the core recognition function is present, typical OCR workflows would benefit from additional tools like batch processing, format conversion, or configuration management.
The toolset is severely incomplete for an OCR domain. It lacks essential operations such as batch processing multiple images, handling different input formats, configuring OCR parameters, or providing text extraction with formatting/layout preservation. The health check tool doesn't meaningfully extend the OCR functionality.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Agent-native document parsing: PDF, scans and FR/EU invoices to structured JSON or Markdown.
OCR and document understanding: extract text from images, then summarize or translate it.
OCR for images and Korean ID documents
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/qiao-925/ocr-mcp-service'
If you have feedback or need assistance with the MCP directory API, please join our Discord server