Unlimited-OCR for Claude Code

把百度 Unlimited-OCR 模型封装成 MCP 工具，让 Claude Code（以及任何支持 MCP 的客户端）能"看懂"任意图片中的文字——不限次数、不花 API 费用、数据完全本地。

中文 / English

---

✨ 特性

• 🔓 无次数限制：模型跑在本地 GPU，没有调用配额、没有 token 计费
• 🔒 数据不出本机：图片在本地推理，敏感文档（合同、发票、保单）可放心处理
• 🧩 MCP 原生接入：Claude Code 装上即用，模型自动调用，无需手写 prompt
• 📄 多页文档友好：支持单图、多图一次性识别，保留跨页上下文
• 🎯 场景广泛：扫描件、PDF、截图、表格、手写、繁简体均可

🏗️ 工作原理

┌─────────────────────────┐
│   Claude Code (客户端)    │  你说："识别 inputs/1.jpg"
│   + uocr Skill (规则)    │  → Skill 教模型走 OCR 流程
└───────────┬─────────────┘
            │ MCP 协议 (stdio)
            ▼
┌─────────────────────────┐
│  ocr_mcp_server.py      │  暴露 ocr_image / ocr_multi 工具
│  (FastMCP Server)       │
└───────────┬─────────────┘
            │ HTTP /v1/chat/completions (OpenAI 兼容)
            ▼
┌─────────────────────────┐
│  serve_ocr.py           │  加载 baidu/Unlimited-OCR 模型
│  (HTTP API :10000)      │  常驻显存，单卡串行推理
└─────────────────────────┘

两层架构：serve_ocr.py 负责加载模型并暴露 HTTP API；ocr_mcp_server.py 把它包装成 MCP 工具。这样模型只加载一次，Claude Code 重启无需重新加载。

---

📋 环境要求

项目	要求
GPU	NVIDIA GPU，建议 ≥ 8GB 显存（bfloat16）
CUDA	与 PyTorch 版本匹配
Python	3.10+
磁盘	模型权重约 6.3GB（首次下载）
操作系统	Windows / Linux / macOS（macOS 需 CPU 推理，较慢）

🚀 快速开始

第一步：克隆项目

git clone <your-repo-url> uocr-workspace
cd uocr-workspace

第二步：创建 Python 环境

conda create -n uocr python=3.10 -y
conda activate uocr

# 安装 PyTorch（按你的 CUDA 版本选，参考 https://pytorch.org）
# 例如 CUDA 12.1:
pip install torch --index-url https://download.pytorch.org/whl/cu121

# 安装项目依赖
pip install -r requirements.txt

第三步：启动 OCR 服务（关键，必做）

# 首次需设 HuggingFace 镜像（国内用户）
# PowerShell:
$env:HF_ENDPOINT = "https://hf-mirror.com"
# bash:
export HF_ENDPOINT=https://hf-mirror.com

# 启动（首次会下载模型，约 6.3GB）
python serve_ocr.py

看到类似输出即成功：

[启动] 正在加载模型（首次会从 HuggingFace 下载，需设 HF_ENDPOINT 镜像）...
[启动] 模型加载完成，耗时 120.5s | GPU: NVIDIA GeForce RTX 4090
INFO:     Uvicorn running on http://127.0.0.1:10000

⚠️ 这一步是 MCP 能用的前提。serve_ocr.py 必须保持运行，Claude Code 才能调用 OCR。建议把它放在单独的终端窗口里常驻。

验证服务在线：

curl http://127.0.0.1:10000/v1/models

第四步：在 Claude Code 中接入

进入项目目录，启动 Claude Code：

claude

项目根目录已经配置好 .mcp.json 和 .claude/skills/uocr/SKILL.md，Claude Code 会自动加载。首次会询问是否信任项目级 MCP 配置，选 Yes。

输入 /mcp 确认 uocr 已连接，能看到两个工具：

• mcp__uocr__ocr_image
• mcp__uocr__ocr_multi

第五步：使用

直接对 Claude Code 说：

识别 docs/2.png

或：

/uocr 识别 docs/2.png，告诉我内容

Claude 会自动按 Skill 流程调用 OCR，整理结果后返回。

📁 项目结构

uocr-workspace/
├── serve_ocr.py              # 模型服务（HTTP API，必须先启动）
├── ocr_mcp_server.py         # MCP Server（包装 HTTP API）
├── requirements.txt          # Python 依赖
├── run_ocr.py                # 命令行推理脚本（可选，脱离 MCP 单独跑）
├── probe_infer.py            # 推理调试脚本
├── test_api.py               # HTTP API 测试
│
├── .mcp.json                 # Claude Code 项目级 MCP 配置
├── .claude/
│   └── skills/uocr/SKILL.md  # OCR 使用规则 Skill
│
├── inputs/                   # 放待识别的图片（已 gitignore 大 PDF）
└── outputs/                  # 识别结果输出（gitignore）

🔧 配置

修改服务端口

serve_ocr.py 默认监听 127.0.0.1:10000。如需修改：

1. 改 serve_ocr.py 顶部的 PORT = 10000
2. 同步改 ocr_mcp_server.py 顶部的 SERVER_URL = "http://127.0.0.1:10000"

全局可用（跨项目）

默认 .mcp.json 是项目级配置。如想让所有项目都能用：

claude mcp add -s user uocr \
  "<你的 conda 环境路径>/python.exe" \
  "<项目绝对路径>/ocr_mcp_server.py"

并把 .claude/skills/uocr/ 复制到 ~/.claude/skills/uocr/。

❓ 常见问题

<details> <summary><b>Q: Claude Code 调用 OCR 一直卡住，最后超时？</b></summary> 修改mcp的超时时间，建议修改为30分钟。 serve_ocr.py 没启动，或端口被占。先 curl http://127.0.0.1:10000/v1/models 确认服务在线。 </details>

<details> <summary><b>Q: 模型下载很慢 / 连不上 HuggingFace？</b></summary>

设镜像：export HF_ENDPOINT=https://hf-mirror.com（国内推荐）。 </details>

<details> <summary><b>Q: 显存不够（OOM）？</b></summary>

• 确保用 bfloat16 加载（默认已开启）
• 关闭其他占显存的程序
• 单张图不要超过 4K 分辨率 </details>

<details> <summary><b>Q: 想在别的 MCP 客户端用（如 Cursor、Cline）？</b></summary>

完全兼容。只要客户端支持 MCP，把 .mcp.json 里的配置复制到对应客户端的 MCP 配置即可。 </details>

<details> <summary><b>Q: 不想用 Claude Code，只想命令行跑？</b></summary>

python run_ocr.py --mode single -i inputs/1.jpg -o outputs
python run_ocr.py --mode pdf -i doc.pdf -o outputs --dpi 300

</details>

---

🙏 致谢

• 百度 Unlimited-OCR —— 强大的多语言 OCR 基础模型
• Model Context Protocol —— Anthropic 的 MCP 协议
• Claude Code —— Anthropic 的官方 CLI

📄 License

MIT — 见 LICENSE

English version: README.en.md