# macOS 原生 OCR MCP 服务
利用 macOS 内置的强大 Vision 框架，为 Claude 及其他 MCP 客户端提供离线、高精度的 OCR 识别能力。
## 目录
- [功能特性](#功能特性)
- [环境要求](#环境要求)
- [安装与使用](#安装与使用)
- [MCP 工具文档](#mcp-工具文档)
- [Claude Skill 使用指南](#claude-skill-使用指南)
- [最佳实践](#最佳实践)
- [常见问题](#常见问题)
## 功能特性
- **多语言支持**：原生支持中文（简/繁）、英文及中英混排，精准识别率高。
- **PDF 全面支持**：内置 PDF 渲染引擎，可自动处理多页 PDF 文档。
- **智能区块聚合 (Block Aggregation)**：
- 针对复杂表格和段落进行优化，不再简单按行切分。
- 自动识别并保留单元格内容的完整性，避免跨列内容混杂。
- 支持智能纠错，自动合并被排版截断的中文长句。
- **LLM 友好输出**：提供结构化的 JSON 数据（包含语义块 Block、坐标 BBox、原始行 Lines），完美适配 LLM 文档重建场景。
- **隐私安全**：所有数据均在 macOS 本地处理，无需上传云端，无需 API Key。
- **零配置**：通过 `uv` 安装运行，轻量且快速。
## 环境要求
- macOS 10.15+ (Catalina) 或更高版本。
- Python 3.10+。
- 已安装 [uv](https://github.com/astral-sh/uv) (`brew install uv`)。
## 安装与使用
你可以直接通过 `uvx` 使用此 MCP 服务，无需克隆代码仓库。
### Claude Desktop 配置
请将以下内容添加到你的 `~/Library/Application Support/Claude/claude_desktop_config.json` 文件中：
```json
{
"mcpServers": {
"macos-ocr": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/wenjiazhu/macos-ocr-mcp.git",
"macos-ocr"
]
}
}
}
```
*注意：请确保使用正确的 Git 仓库地址。*
如果需要强制更新到最新版本，可以在 `args` 列表中添加 `"--refresh"` 参数。
### 本地开发
1. 克隆仓库：
```bash
git clone https://github.com/wenjiazhu/macos-ocr-mcp.git
cd macos-ocr-mcp
```
2. 使用 `uv` 运行：
```bash
# 运行测试脚本 (输出纯文本)
uv run src/ocr.py path/to/image.png
# 运行 MCP 服务器
uv run src/server.py
```
---
## MCP 工具文档
### 工具列表
本项目提供两个 MCP 工具：
1. **`read_image_text`** - 提取图片或 PDF 中的纯文本
2. **`read_image_layout`** - 提取结构化的版面信息
### 工具选择指南
#### 使用 `read_image_text` 的场景
- ✅ 只需要获取纯文本内容，不需要排版信息
- ✅ 快速提取文档中的可读文本
- ✅ 进行文本搜索、内容分析或摘要
- ✅ 将 OCR 结果用于简单的字符串处理
**优势**：
- 输出简洁，只返回纯文本字符串
- 已自动进行段落合并和表格优化
- 适合简单的文本处理需求
#### 使用 `read_image_layout` 的场景
- ✅ 需要保留或还原文档的原始排版
- ✅ 处理包含表格、多栏布局的复杂文档
- ✅ 需要 LLM 重建文档结构
- ✅ 需要定位文本在图片中的位置
- ✅ 需要将 OCR 结果转换为结构化格式（CSV、Markdown 等）
**优势**：
- 返回结构化 JSON 数据，包含文本块、坐标和语义信息
- 保留完整的版面布局信息
- 支持精确的文档重建和格式转换
### `read_image_text`
识别并提取图片或 PDF 中的纯文本。会自动进行段落合并和表格优化。
- **输入**: `image_path` (图片或 PDF 的绝对路径)
- **输出**: 文本字符串
### `read_image_layout`
提取结构化的版面信息，专为 LLM 重建文档设计。
- **输入**: `image_path` (图片或 PDF 的绝对路径)
- **输出**: JSON 字符串，包含多个 "Block" 对象。每个 Block 包含：
- `text`: 合并纠错后的语义文本。
- `bbox`: 文本块的归一化坐标 (x, y, w, h)，用于还原排版。
- `lines`: 构成该块的原始行信息（可选，用于精细分析）。
#### 数据结构说明
`read_image_layout` 返回的 JSON 结构如下：
```json
[
{
"text": "合并纠错后的语义文本",
"bbox": {
"x": 0.0, // 归一化横坐标 [0-1]
"y": 0.0, // 归一化纵坐标 [0-1]
"w": 0.5, // 归一化宽度 [0-1]
"h": 0.2 // 归一化高度 [0-1]
},
"lines": [ // 构成该块的原始行信息（可选）
{
"text": "原始行文本",
"bbox": {...}
}
]
}
]
```
**bbox 坐标说明**: 所有坐标均为归一化值（0-1），表示相对于图像尺寸的位置，可用于按位置重建文档布局。
---
## Claude Skill 使用指南
本项目包含 `macos-ocr-helper` Claude Skill，提供更丰富的使用场景和最佳实践指导。
### 快速开始
直接在 Claude 对话中使用，Skill 会自动触发并提供建议。典型使用方式：
1. **快速提取文本**：
```
请帮我把这张图片中的文字提取出来
```
2. **转换文档格式**：
```
把这个 PDF 转换成 Markdown 格式
```
3. **处理表格**：
```
将这个表格截图转换成 CSV 格式
```
### 核心使用场景
#### 场景 1：快速提取纯文本
**适用场景**: 只需要获取可复制的文本内容
**提示词模板**:
```
请调用 macos-ocr 的 read_image_text 读取以下文件并输出识别结果：
image_path=/绝对路径/xxx.png
要求：
1. 只输出 OCR 文本本身，不要添加解释、标题或多余前后缀
2. 尽量保留原有换行与段落；不要翻译，不要总结
```
**返回格式**: 纯文本字符串
---
#### 场景 2：图片/PDF → Markdown
**适用场景**: 需要将扫描文档转换为 Markdown 格式，尽量还原原有排版
**提示词模板**:
```
请调用 macos-ocr 的 read_image_layout 读取以下文件：
image_path=/绝对路径/xxx.pdf
然后将返回的 blocks 按 bbox 近似还原为 Markdown：
- 标题/小标题、段落、列表分别用合适的 Markdown 语法表示
- 识别出表格时输出为 Markdown 表格（必要时补齐空单元格）
- 多页内容用清晰的分页分隔（例如：--- Page 1 ---）
只输出最终 Markdown，不要输出中间 JSON。
```
**返回格式**: Markdown 文档
---
#### 场景 3：扫描表格 → CSV
**适用场景**: 将包含表格的图片转换为 CSV 格式，方便导入 Excel、Numbers 等表格软件
**提示词模板**:
```
请调用 macos-ocr 的 read_image_layout 读取以下文件：
image_path=/绝对路径/table.png
目标：把图片中的"表格"转换成 CSV。
要求：
1. 只输出 CSV（逗号分隔），不要额外解释
2. 保留表头；不要丢列或丢行；空单元格也要保留为空
3. 如果存在合并单元格：优先用空值或重复值保证列数一致，并在 CSV 末尾另起一行用 NOTE: 简要说明处理方式
```
**返回格式**: CSV 格式文本
---
#### 场景 4：发票/收据 → 结构化 JSON
**适用场景**: 提取发票、收据等票据中的关键信息，转换为结构化 JSON
**提示词模板**:
```
请调用 macos-ocr 的 read_image_text 读取以下文件：
image_path=/绝对路径/receipt.jpg
请将识别内容抽取为严格 JSON（只输出 JSON）：
{
"merchant": string|null,
"date": "YYYY-MM-DD"|null,
"currency": string|null,
"total": number|null,
"tax": number|null,
"items": [{"name": string, "qty": number|null, "unit_price": number|null, "amount": number|null}],
"payment_method": string|null,
"invoice_no": string|null
}
规则：金额统一用数字；无法确认就填 null；不要编造。
```
**返回格式**: JSON 对象
---
#### 场景 5：代码/终端截图 → 可复制代码块
**适用场景**: 从代码或终端截图提取可执行代码，自动纠正常见 OCR 错误
**提示词模板**:
```
请调用 macos-ocr 的 read_image_text 读取以下文件：
image_path=/绝对路径/code.png
把结果整理成一个 Markdown 代码块输出：
1. 去掉行号、提示符（如 $、>>>）等无关字符
2. 修正常见 OCR 错误（如 0/O、1/l/I、:;、引号、括号配对）
3. 保持原有缩进
只输出代码块（例如 ```python ... ```），不要额外解释。
```
**返回格式**: Markdown 代码块
---
#### 场景 6：论文/合同扫描件 → 结构化提纲
**适用场景**: 分析长篇文档的结构，提取提纲和关键信息
**提示词模板**:
```
请调用 macos-ocr 的 read_image_text 读取以下文件：
image_path=/绝对路径/doc.png
基于 OCR 文本输出：
1) 结构化提纲（H1/H2/H3）
2) "关键点"列表（最多 10 条）
3) "需要人工确认的疑点/缺失"列表（例如数字不清、条款编号断裂）
要求：：不要杜撰；引用原文时用原句；输出用中文。
```
**返回格式**: 结构化提纲文本
---
## 最佳实践
### 提示词编写建议
#### 1. 明确指定工具
❌ **不推荐**:
```
帮我读取这张图片
```
✅ **推荐**:
```
请调用 macos-ocr 的 read_image_text 读取以下文件：
image_path=/绝对路径/xxx.png
```
#### 2. 明确文件路径
❌ **不推荐**:
```
image_path=image.png
```
✅ **推荐**:
```
image_path=/Users/username/Documents/image.png
```
#### 3. 清晰说明输出格式
❌ **不推荐**:
```
读取图片并给我结果
```
✅ **推荐**:
```
只输出 OCR 文本本身，不要添加解释、标题或多余前后缀
```
### 处理复杂文档的建议
#### 多页 PDF 处理
macOS OCR 原生支持多页 PDF。当处理多页文档时：
- 使用 `read_image_layout` 可以按 bbox 坐标分页处理
- 在提示词中明确要求分页分隔（例如：`--- Page N ---`）
- 如果需要逐页分析，可以在提示词中指定页面范围
#### 表格识别优化
对于包含表格的文档：
1. 使用 `read_image_layout` 获取结构化数据
2. 利用 bbox 坐标信息识别表格边界
3. 在提示词中明确说明表格处理规则
4. 处理合并单元格时，要求输出处理方式说明
#### 中英文混排文档
macOS OCR 原生支持中英文混排。处理建议：
1. 明确输出语言要求（中文/英文/混合）
2. 保留原始文档的语言排版
3. 避免自动翻译或语言转换
### 质量优化策略
#### 常见 OCR 错误类型
1. **字符混淆**:
- `0` 与 `O` 混淆
- `1`、`l`、`I` 混淆
- `:` 与 `;` 混淆
- `引号`、`括号`配对错误
2. **标点符号错误**:
- 句号误识别为逗号
- 引号方向错误
3. **行分割错误**:
- 段落被错误分割
- 单词被截断
#### 针对不同文档类型的优化
**对于代码类文档**：
```
把结果整理成一个 Markdown 代码块输出：
1. 去掉行号、提示符（如 $、>>>）等无关字符
2. 修正常见 OCR 错误（如 0/O、1/l/I、:;、引号、括号配对）
3. 保持原有缩进
```
**对于正式文档**：
```
基于 OCR 文本输出：
1) 结构化提纲（H1/H2/H3）
2) "关键点"列表（最多 10 条）
3) "需要人工确认的疑点/缺失"列表（例如数字不清、条款编号断裂）
要求：不要杜撰；引用原文时用原句；输出用中文。
```
### 性能优化建议
#### 大文件处理
对于包含大量图片或多页 PDF 的文档：
1. 如果可能，先预处理文件（压缩、裁剪）
2. 考虑分批处理，避免一次性处理过多内容
3. 在提示词中明确指定处理范围
#### 批量处理
如需批量处理多个文件：
1. 在提示词中明确列出所有文件路径
2. 要求清晰分隔每个文件的结果
3. 可以要求输出处理进度或摘要
---
## 常见问题
### 问题：识别结果质量不佳
**排查步骤**：
1. 检查图片分辨率是否足够（建议 300 DPI 以上）
2. 检查图片是否清晰、无模糊
3. 尝试提高图片对比度
4. 检查图片倾斜角度，可能需要旋转矫正
### 问题：多页 PDF 处理失败
**排查步骤**：
1. 确认 PDF 文件完整性
2. 检查 PDF 是否有密码保护
3. 尝试使用 `read_image_layout` 获取更多信息
### 问题：坐标信息不准确
**排查步骤**：
1. 确认图片尺寸和方向
2. 检查归一化坐标是否在 [0, 1] 范围内
3. 使用 `read_image_layout` 获取完整结构信息
### 隐私和安全
**数据安全**：
- ✅ 所有数据在 macOS 本地处理
- ✅ 不需要上传到云端
- ✅ 不需要 API Key
- ✅ 完全离线可用
**敏感文档处理**：
处理敏感文档（如合同、发票、个人证件）时：
1. 使用绝对路径确保文档位置明确
2. 避免在提示词中暴露敏感信息
3. 处理完成后可以删除本地临时副本
---
## 技术文档
本项目包含完整的技术文档，适合开发者深入理解项目架构和 API。
- [技术文档索引](./docs/INDEX.md) - 文档导航和快速入口
- [技术架构文档](./docs/TECHNICAL_ARCHITECTURE.md) - 系统架构、设计决策、核心算法
- [部署与集成指南](./docs/DEPLOYMENT_GUIDE.md) - 安装、配置、部署、集成
- [API 参考文档](./docs/API_REFERENCE.md) - MCP 工具 API、Python 模块 API、示例
---
## 技术支持
- GitHub Issues: https://github.com/wenjiazhu/macos-ocr-mcp/issues
- 文档更新时间: 2026-01-18
## License
MIT License
