Metadata-Version: 2.4
Name: ocr-mcp-server
Version: 1.0.0
Summary: Unified OCR MCP Server - PaddleOCR / Hunyuan / GLM-4V via Model Context Protocol
Project-URL: Homepage, https://github.com/yourname/ocr-mcp-server
Project-URL: Repository, https://github.com/yourname/ocr-mcp-server
Project-URL: Issues, https://github.com/yourname/ocr-mcp-server/issues
License: MIT
License-File: LICENSE
Keywords: ai,glm,hunyuan,llm,mcp,ocr,paddleocr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.3.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: paddleocr
Requires-Dist: paddleocr>=2.8.0; extra == 'paddleocr'
Requires-Dist: paddlepaddle>=2.6.0; extra == 'paddleocr'
Provides-Extra: pdf
Requires-Dist: pymupdf>=1.23.0; extra == 'pdf'
Description-Content-Type: text/markdown

# ocr-mcp-server

[![PyPI](https://img.shields.io/pypi/v/ocr-mcp-server)](https://pypi.org/project/ocr-mcp-server/)
[![Python](https://img.shields.io/pypi/pyversions/ocr-mcp-server)](https://pypi.org/project/ocr-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

统一 OCR MCP Server，通过 [MCP 协议](https://modelcontextprotocol.io) 对外暴露多家 OCR 引擎。
支持 Windows 本地运行，可发布到 PyPI，可供 Claude Desktop / Cursor / Trae / 自定义 Java-Python 项目调用。

## 支持的 OCR Provider

| Provider | 类型 | 特点 | 配置方式 |
|----------|------|------|---------|
| `paddleocr` | 本地运行 | 无需网络，中英文/多语言，数据不出本机 | `pip install "ocr-mcp-server[paddleocr]"` |
| `hunyuan` | 腾讯云 API | 高精度，手写/表格/发票，按量计费 | 设置 `HUNYUAN_SECRET_ID` + `HUNYUAN_SECRET_KEY` |
| `glm` | 智谱 AI API | GLM-4V 大模型，理解复杂版式，Flash 有免费额度 | 设置 `GLM_API_KEY` |

## 安装

```bash
# 基础安装（仅云 API，不含 PaddleOCR）
pip install ocr-mcp-server

# 含 PaddleOCR 本地识别（Windows 推荐）
pip install "ocr-mcp-server[paddleocr]"
```

> Windows 安装 PaddleOCR 注意：需要先安装 Visual C++ Redistributable，
> 并建议使用 Python 3.9-3.11。

## 快速使用

### 1. 配置环境变量

创建 `.env` 文件或直接在系统环境变量中设置：

```bash
# PaddleOCR（安装后自动启用，无需配置）

# 腾讯混元 OCR（可选）
HUNYUAN_SECRET_ID=AKIDxxxxxxxxxxxxxxxx
HUNYUAN_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 智谱 GLM-OCR（可选）
GLM_API_KEY=xxxxxxxx.xxxxxxxxxxxxxxxx

# 指定默认引擎（可选，不设置则优先使用 paddleocr）
OCR_DEFAULT_PROVIDER=paddleocr
```

### 2. 运行服务

```bash
# stdio 模式（供 Claude Desktop / Cursor / Trae 调用）
ocr-mcp-server

# HTTP 模式（供远程服务器上的 AI 应用调用）
ocr-mcp-server --transport streamable-http --port 8000

# 指定默认 Provider
ocr-mcp-server --default-provider glm
```

## MCP 客户端配置

### Claude Desktop

编辑 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：

```json
{
  "mcpServers": {
    "ocr": {
      "command": "ocr-mcp-server",
      "env": {
        "GLM_API_KEY": "your_glm_api_key",
        "HUNYUAN_SECRET_ID": "your_secret_id",
        "HUNYUAN_SECRET_KEY": "your_secret_key"
      }
    }
  }
}
```

### Cursor / Trae IDE

编辑 `.cursor/mcp.json` 或 Trae 的 MCP 配置：

```json
{
  "mcpServers": {
    "ocr": {
      "command": "ocr-mcp-server",
      "args": ["--default-provider", "paddleocr"]
    }
  }
}
```

### 远程 HTTP 部署（供 Java 项目调用）

```bash
# 服务器端启动
ocr-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000
```

Java 项目中通过 Spring AI MCP Client 调用：
```java
// pom.xml 引入 spring-ai-mcp-client-spring-boot-starter
McpClient client = McpClient.sync(
    new HttpClientSseClientTransport("http://your-server:8000/sse")
).build();
client.initialize();
CallToolResult result = client.callTool(
    new CallToolRequest("ocr_recognize_from_url",
        Map.of("image_url", "https://example.com/invoice.jpg"))
);
```

Python 项目调用：
```python
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client("http://your-server:8000/mcp") as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool(
            "ocr_recognize_from_url",
            {"image_url": "https://example.com/invoice.jpg"}
        )
```

## 暴露的 MCP Tools

| Tool | 说明 | 必填参数 |
|------|------|---------|
| `ocr_recognize_from_url` | 通过图片 URL 识别文字 | `image_url` |
| `ocr_recognize_from_base64` | 通过 Base64 图片识别文字 | `base64_image` |
| `ocr_list_providers` | 列出所有 OCR 引擎及状态 | 无 |

所有工具支持可选参数：
- `provider`: 指定 OCR 引擎（不填自动选择）
- `response_format`: `markdown`（默认）或 `json`

## 开发与发布

```bash
# 克隆项目
git clone https://github.com/yourname/ocr-mcp-server
cd ocr-mcp-server

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v

# 本地调试（MCP Inspector）
npx @modelcontextprotocol/inspector ocr-mcp-server

# 构建
python -m build

# 发布到 PyPI
twine upload dist/*

# 发布到 TestPyPI（先测试）
twine upload --repository testpypi dist/*
```

## 项目结构

```
ocr-mcp-server/
├── pyproject.toml                  # 包配置、依赖、CLI 入口
├── README.md
├── LICENSE
├── scripts/
│   └── evaluation.xml              # MCP 标准测试集
├── src/ocr_mcp_server/
│   ├── __init__.py
│   ├── __main__.py                 # CLI 入口: ocr-mcp-server
│   ├── config.py                   # 环境变量配置
│   ├── server.py                   # FastMCP Server + 3 个 Tools
│   ├── providers/
│   │   ├── __init__.py             # BaseOcrProvider 基类 + OcrResult 模型
│   │   ├── paddleocr_provider.py   # PaddleOCR（本地）
│   │   ├── hunyuan_provider.py     # 腾讯混元OCR
│   │   └── glm_provider.py         # 智谱 GLM-4V OCR
│   └── utils/
│       └── image.py                # URL 下载 + Base64 解码工具
└── tests/
    ├── test_providers.py
    └── test_image_utils.py
```

## 许可证

MIT
