macOS 原生 OCR MCP 服务

利用 macOS 内置的强大 Vision 框架，为 Claude 及其他 MCP 客户端提供离线、高精度的 OCR 识别能力。

目录

• 功能特性

• 环境要求

• 安装与使用

• MCP 工具文档

• 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 (brew install uv)。

安装与使用

你可以直接通过 uvx 使用此 MCP 服务，无需克隆代码仓库。

Claude Desktop 配置

请将以下内容添加到你的 ~/Library/Application Support/Claude/claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "macos-ocr": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/wenjiazhu/macos-ocr-mcp.git",
        "macos-ocr"
      ]
    }
  }
}

注意：请确保使用正确的 Git 仓库地址。

如果需要强制更新到最新版本，可以在 args 列表中添加 "--refresh" 参数。

本地开发

1. 克隆仓库：

   git clone https://github.com/wenjiazhu/macos-ocr-mcp.git
   cd macos-ocr-mcp

2. 使用 uv 运行：

   # 运行测试脚本 (输出纯文本)
   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 结构如下：

[
  {
    "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。

• 技术文档索引 - 文档导航和快速入口

• 技术架构文档 - 系统架构、设计决策、核心算法

• 部署与集成指南 - 安装、配置、部署、集成

• API 参考文档 - MCP 工具 API、Python 模块 API、示例

技术支持

• GitHub Issues: https://github.com/wenjiazhu/macos-ocr-mcp/issues

• 文档更新时间: 2026-01-18

License

MIT License