# OCR MCP Server

**基于 Claude Vision 能力的文档文字识别 MCP 工具**，无需 Tesseract/PaddleOCR 等第三方 OCR 引擎，直接利用大模型多模态视觉能力提取文字。

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-Server-green.svg)](https://modelcontextprotocol.io/)
[![Claude](https://img.shields.io/badge/Claude-Vision-orange.svg)](https://www.anthropic.com/)

## ✨ 特性

- **零 OCR 引擎依赖** — 不安装 Tesseract、PaddleOCR，全部识别能力来自 Claude Vision API
- **三种工具** — 图片识别、智能 PDF 识别、强制 OCR 扫描件
- **智能降级** — 文字版 PDF 直接提取内嵌文字，零 API 成本；扫描件自动转图片走 Vision
- **结构化输出** — 支持 Markdown 表格、JSON、纯文本，适配表格/表单/手写体等场景
- **即插即用** — 配置 Claude Desktop 后，自然语言直接调用

## 🛠 工具

| 工具 | 用途 |
|------|------|
| `recognize_image` | 识别图片文字，支持印刷体、手写体、表格，输出 Markdown/JSON |
| `recognize_pdf` | 智能处理 PDF：文字版直接提取内嵌文字（省 token），扫描件自动走 Vision OCR |
| `recognize_pdf_ocr` | 强制全页 Vision OCR，适配纯扫描件/手写 PDF |

## 📦 安装

```bash
# 克隆仓库
git clone https://github.com/你的用户名/ocr-mcp-server.git
cd ocr-mcp-server

# 安装依赖（仅 mcp / anthropic / PyMuPDF）
pip install -r requirements.txt

# 设置 Anthropic API Key
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
```

## ⚙️ 配置 Claude Desktop

编辑 `claude_desktop_config.json`：

- **macOS**: `~/Library/Application Support/Claude/`
- **Windows**: `%APPDATA%\Claude\`

```json
{
  "mcpServers": {
    "ocr": {
      "command": "python",
      "args": ["/你的绝对路径/ocr-mcp-server/server.py"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-xxxxx"
      }
    }
  }
}
```

重启 Claude Desktop 即可使用。

## 🚀 使用

在 Claude Desktop 中直接用自然语言触发：

- *"帮我识别这张图片里的文字"* → 自动调用 `recognize_image`
- *"提取这个 PDF 里的表格"* → 自动调用 `recognize_pdf`
- *"这个扫描件里写了什么"* → 自动调用 `recognize_pdf_ocr`

## 🧠 工作原理

```
图片  ──→ base64 编码 ──→ Claude Vision API ──→ 结构化文本
PDF   ──→ PyMuPDF 检测文字层
            ├─ 有文字层 → 直接提取（零成本）
            └─ 扫描件   ──→ 转图片 ──→ base64 ──→ Vision API
```

核心思路：用 LLM 的视觉理解能力替代传统 OCR 管线，对复杂排版、表格、手写体、印章等场景的理解更强，且能保持语义结构。

## 🔧 技术栈

- **[mcp](https://github.com/modelcontextprotocol/python-sdk)** — MCP 协议官方 Python SDK（FastMCP）
- **[anthropic](https://github.com/anthropics/anthropic-sdk-python)** — Claude API 官方客户端
- **PyMuPDF** — PDF 渲染与内嵌文字提取

## 📄 License

MIT