# Unlimited-OCR for Claude Code

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

中文 / [English](README.en.md) 

---

## ✨ 特性

- 🔓 **无次数限制**：模型跑在本地 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 推理，较慢） |

## 🚀 快速开始

### 第一步：克隆项目

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

### 第二步：创建 Python 环境

```bash
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 服务（**关键，必做**）

```bash
# 首次需设 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。建议把它放在单独的终端窗口里常驻。

**验证服务在线：**

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

### 第四步：在 Claude Code 中接入

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

```bash
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，整理结果后返回。

![Claude Code 运行效果](docs/claudecode运行效果.png)
---

## 📁 项目结构

```
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` 是项目级配置。如想让所有项目都能用：

```bash
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>

```bash
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](https://huggingface.co/baidu/Unlimited-OCR) —— 强大的多语言 OCR 基础模型
- [Model Context Protocol](https://modelcontextprotocol.io/) —— Anthropic 的 MCP 协议
- [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) —— Anthropic 的官方 CLI

## 📄 License

MIT — 见 [LICENSE](LICENSE)

> English version: [README.en.md](README.en.md)