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

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 的客户端调用以下工具：

| 工具名 | 参数 | 说明 | 调用示例 | | --- | --- | --- | --- | | ocr_image | image_path: str \| list[str] | 对单图或多图执行全文 OCR。 | ocr_image("D:/images/a.png")<br>ocr_image(["D:/images/a.png", "D:/images/b.png"]) | | ocr_region_by_description | file_path: str, region_description: str, page_number: int = 1 | 根据文本描述先定位区域，再进行局部 OCR，支持图片和 PDF。 | ocr_region_by_description("D:/images/large.png", "左上角标题区域")<br>ocr_region_by_description("D:/docs/report.pdf", "第3段结论框", 2) | | ocr_region_by_bbox | file_path: str, x1: int, y1: int, x2: int, y2: int, page_number: int = 1 | 通过对角坐标直接框选区域 OCR，支持图片和 PDF。 | ocr_region_by_bbox("D:/images/large.png", 120, 80, 920, 460)<br>ocr_region_by_bbox("D:/docs/report.pdf", 100, 120, 430, 280, 2) | | ocr_cached_frames_summary | max_frames: int = 0 | 对缓存帧逐个重新 OCR，结合来源路径、缓存时间、上次 OCR 时间生成统一调查提示词。0 表示处理全部缓存帧。 | ocr_cached_frames_summary()<br>ocr_cached_frames_summary(10) | | what_have_you_seen | max_frames: int = 10 | 面向自然问法的高触发入口（如“你看见过什么”），内部调用缓存汇总并返回调查提示词。 | what_have_you_seen()<br>what_have_you_seen(20) |

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：请先手动裁剪或降低分辨率。