macOS Native OCR MCP Server

# macOS 原生 OCR MCP 服务 利用 macOS 内置的强大 Vision 框架，为 Claude 及其他 MCP 客户端提供离线、高精度的 OCR 识别能力。 ## 功能特性 - **多语言支持**：原生支持中文（简/繁）、英文及中英混排，精准识别率高。 - **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 ``` ## 工具列表 (Tools) ### `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_text`。 - 需要“按版面重建”（表格/多栏/段落/坐标）：优先用 `read_image_layout`。 ### 1) 快速提取纯文本（不重排、不总结） ```text 请调用 macos-ocr 的 read_image_text 读取以下文件并输出识别结果： image_path=/绝对路径/xxx.png 要求： 1. 只输出 OCR 文本本身，不要添加解释、标题或多余前后缀。 2. 尽量保留原有换行与段落；不要翻译，不要总结。 ``` ### 2) 图片/PDF → Markdown（尽量还原排版） ```text 请调用 macos-ocr 的 read_image_layout 读取以下文件： image_path=/绝对路径/xxx.pdf 然后将返回的 blocks 按 bbox 近似还原为 Markdown： - 标题/小标题、段落、列表分别用合适的 Markdown 语法表示 - 识别出表格时输出为 Markdown 表格（必要时补齐空单元格） - 多页内容用清晰的分页分隔（例如：--- Page 1 ---） 只输出最终 Markdown，不要输出中间 JSON。 ``` ### 3) 扫描表格 → CSV（可直接导入表格软件） ```text 请调用 macos-ocr 的 read_image_layout 读取以下文件： image_path=/绝对路径/table.png 目标：把图片中的“表格”转换成 CSV。 要求： 1. 只输出 CSV（逗号分隔），不要额外解释。 2. 保留表头；不要丢列或丢行；空单元格也要保留为空。 3. 如果存在合并单元格：优先用空值或重复值保证列数一致，并在 CSV 末尾另起一行用 NOTE: 简要说明处理方式。 ``` ### 4) 发票/收据 → 结构化 JSON（字段缺失用 null） ```text 请调用 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；不要编造。 ``` ### 5) 代码/终端截图 → 可复制代码块（自动纠错） ```text 请调用 macos-ocr 的 read_image_text 读取以下文件： image_path=/绝对路径/code.png 把结果整理成一个 Markdown 代码块输出： 1. 去掉行号、提示符（如 $、>>>）等无关字符 2. 修正常见 OCR 错误（如 0/O、1/l/I、:;、引号、括号配对） 3. 保持原有缩进 只输出代码块（例如 ```python ... ```），不要额外解释。 ``` ### 6) 论文/合同扫描件 → 结构化提纲 + 关键点（可用于二次加工） ```text 请调用 macos-ocr 的 read_image_text 读取以下文件： image_path=/绝对路径/doc.png 基于 OCR 文本输出： 1) 结构化提纲（H1/H2/H3） 2) “关键点”列表（最多 10 条） 3) “需要人工确认的疑点/缺失”列表（例如数字不清、条款编号断裂） 要求：不要杜撰；引用原文时用原句；输出用中文。 ```