Vision-OCR-MCP

本项目提供一个 MCP OCR 服务，工具名为 ocr_image，用于识别本地图片文字。

新增 ocr_region_by_description，支持按文本描述在大图/PDF 页面中定位局部区域并 OCR。

新增 ocr_region_by_bbox，支持通过对角坐标直接框选区域 OCR。

1. 运行要求

• Python 3.10+

• 可用的多模态模型 API（支持 zhipu 或 openai_compatible）

• 支持图片格式：.jpg .jpeg .png .webp

• 区域 OCR 额外支持：.bmp .tif .tiff .gif .pdf

Related MCP server: ReadPDFx - OCR PDF MCP Server

2. 安装步骤

在项目根目录执行：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

3. 配置模型提供方

默认读取项目根目录 .env.example，也支持同名环境变量。

方式 A：zhipu（示例）

OCR_PROVIDER=zhipu
ZHIPUAI_API_KEY=<YOUR_ZHIPUAI_API_KEY>
ZHIPUAI_MODEL=glm-4v-flash

方式 B：openai_compatible

OCR_PROVIDER=openai_compatible
OCR_API_KEY=<YOUR_API_KEY>
OCR_BASE_URL=https://your-provider.example/v1
OCR_MODEL=<YOUR_VISION_MODEL>

缓存配置（可选）

OCR_CACHE_TARGET_KB=300
OCR_CACHE_MAX_ITEMS=30
OCR_CACHE_DIR=.ocr_cache
OCR_CACHE_AGE_COMPRESS=true
OCR_CACHE_AGE_STEP_DAYS=7
OCR_CACHE_AGE_DECAY=0.12
OCR_CACHE_AGE_MIN_RATIO=0.35

• OCR_CACHE_TARGET_KB：缓存帧压缩目标大小（KB，上限目标值）。

• OCR_CACHE_MAX_ITEMS：缓存队列最多保留帧数，超出后自动淘汰最旧帧。

• OCR_CACHE_DIR：缓存目录。

• OCR_CACHE_AGE_COMPRESS：是否启用按时间衰减压缩。

• OCR_CACHE_AGE_STEP_DAYS：每经过多少天降低一个压缩档位。

• OCR_CACHE_AGE_DECAY：每个档位的目标大小衰减比例（例如 0.12 表示每档再缩小 12%）。

• OCR_CACHE_AGE_MIN_RATIO：压缩目标最小比例，避免过度压缩。

如果 .env.example 中未配置，则回退读取环境变量。

环境变量方式（可选）

当前终端临时生效：

$env:OCR_PROVIDER="zhipu"
$env:ZHIPUAI_API_KEY="<YOUR_ZHIPUAI_API_KEY>"

持久化到用户环境变量（新终端生效）：

setx OCR_PROVIDER "zhipu"
setx ZHIPUAI_API_KEY "<YOUR_ZHIPUAI_API_KEY>"

4. 本地启动 MCP 服务

python server.py

或使用：

run.bat

5. 接入 Claude Desktop

编辑配置文件：

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

示例（Windows 路径按实际修改）：

{
   "mcpServers": {
      "VisionOCR": {
         "command": "python",
         "args": ["D:\\Projects\\mcp\\Vision-OCR-mcp-server\\server.py"],
         "env": {
            "OCR_PROVIDER": "zhipu",
            "ZHIPUAI_API_KEY": "<YOUR_ZHIPUAI_API_KEY>"
         }
      }
   }
}

保存后重启 Claude Desktop。

6. 使用方式

在支持 MCP 的客户端调用以下工具：

6.1 让模型更容易调用 MCP

优先使用明确的“调用工具”表达，模型命中率更高：

• 请调用 what_have_you_seen，告诉我你看见过什么。

• 请调用 ocr_cached_frames_summary(20)，整理历史 OCR 证据。

• 请调用 ocr_region_by_description，对这个 PDF 找标题区域并识别。

7. 已实现能力与限制

• 支持单图/多图 OCR

• 超过 5MB 自动压缩后再上传

• 支持图片格式自动转换后识别（bmp/tiff/gif -> jpeg）

• 支持基于文本描述的区域 OCR（先低分辨率定位，再对局部高分辨率识别）

• 支持对角坐标框选区域 OCR（支持任意两点顺序，自动归一化）

• 历史 OCR 帧自动压缩入缓存，并支持队列淘汰

• 缓存支持按时间分级压缩（越旧压缩越强）

• 支持批量回放缓存帧并生成调查汇总提示词

• 单张本地读取上限 30MB

• 单次最多 10 张图片

8. 常见问题

• 报错 未读取到 ... API_KEY：检查 .env.example 或环境变量中的 key 是否存在。

• 报错 不支持的文件格式：仅支持 .jpg .jpeg .png .webp。

• 报错 图片压缩后仍超过 5MB：请先手动裁剪或降低分辨率。