内容
# macos-vision-mcp
<p align="center">
<img src=".github/assets/hero.jpg" alt="macos-vision-mcp — 本地、私有、离线 OCR，适用于 MCP 兼容的 LLM" width="1200">
</p>
通过适用于任何 MCP 客户端的本地、私有、离线 OCR，降低文档令牌成本约 97% — 无需 API 密钥，无需上传。
[](https://www.npmjs.com/package/macos-vision-mcp)
[](https://www.npmjs.com/package/macos-vision-mcp)
[](https://github.com/woladi/macos-vision-mcp/stargazers)
[](LICENSE)
[](https://developer.apple.com/documentation/vision)
[](#隐私层)
[](#您获得的内容)
[](https://glama.ai/mcp/servers/woladi/macos-vision-mcp)
在您的 AI 看到它之前，本地预先提取文本和图像数据 — 将真实文档的令牌使用量减少约 97%，并返回结构化的段落、行和边界框，以便模型可以将文档重建为 Markdown、HTML、DOCX 或任何其他格式。文件永远不会离开您的 Mac：无需云 API，无需 API 密钥，无需网络请求。
> <sub>**如何衡量约 97%：** 将 44 页扫描的 PDF 以页面图像形式发送，费用约为 73,500 个令牌；使用 `analyze_document` 运行相同的文件，返回约 2,400 个令牌的提取文本和结构（原始页面图像令牌 vs. 提取文本令牌）。您的数字会根据页面密度和分词器而有所不同 — 将 97% 视为数量级，而不是保证。</sub>
**目录：** [快速开始](#快速开始) · [您获得的内容](#您获得的内容) · [为什么不同](#为什么不同) · [可用工具](#可用工具) · [用法](#用法) · [示例工作流程](#示例工作流程) · [配置](#配置) · [隐私层](#隐私层)
## 您获得的内容
- 通过 Apple Vision Framework 对图像和 PDF（JPG、PNG、HEIC、TIFF、多页 PDF）进行 OCR。
- 约 97% 的令牌减少：44 页的 PDF 费用约为 2,400 个令牌，而不是 73,500 个。
- 按阅读顺序的段落 + 原始文本块，带有边界框 — 模型可以重建文档为任何输出格式（Markdown、HTML、DOCX、JSON），而不是有损的纯文本转储。
- 人脸检测、条形码/二维码读取和图像分类 — 均在设备上。
- 完整的文档处理流程：OCR + 人脸 + 条形码 + 矩形在一个工具调用中。
- 与 Claude Code、Claude Desktop 和 Cursor 合作 — 任何 MCP 兼容的客户端。
- 没有文件上传到任何服务器 — 处理完全在您的 Mac 上进行。
- 安装后 100% 离线 — 由 Apple Vision Framework 提供支持，与 Photos.app 中的 Live Text 相同。
## ❌ 没有 / ✅ 有
❌ **没有 macos-vision-mcp：**
- 发送 44 页的 PDF 费用约为 73,500 个令牌
- 每个图像、发票或合同都通过云 API
- 敏感文档在每次请求时离开您的机器
✅ **有 macos-vision-mcp：**
- 本地 Apple Vision 预先提取文本，然后再让 Claude 看到它
- 相同的 44 页 PDF 仅需约 2,400 个令牌 — 减少 97%
- 文件永远不会离开您的 Mac
## 为什么不同
大多数适用于 LLM 的 OCR 选项要么将您的文档发送到云视觉 API，要么需要您建立和调整自己的引擎。此工具运行在 Apple 的设备视觉框架上 — 与 Photos.app 中的 Live Text 相同的引擎 — 因此提取是免费、私有和即时的。
| | macos-vision-mcp | 云视觉 OCR（GPT-4o、Google Vision、Mistral OCR） | 基于 Tesseract 的 MCP |
| ----------- | ----------------------------------------------------------- | ----------------------------------------------------- | -------------------------------- |
| **成本** | 0 美元 — 无每页或每令牌费用 | 按次/每页计费 | 0 美元，但需自行托管 |
| **离线** | 安装后支持 | 否 — 每个页面都需要网络连接 | 支持 |
| **隐私** | 文件永远不会离开您的 Mac | 文档上传到第三方 | 本地 |
| **设置** | 一个命令，无需密钥 | API 密钥 + 账单账户 | 安装 + 语言数据 + 调整 |
| **质量** | Apple Vision（在干净的扫描件、收据、截图上表现良好） | 一般较高 | 取决于扫描质量 |
权衡是诚实的：它仅限于 macOS，对于严重倾斜或对比度较低的扫描件，云模型可能仍然能读取更多。对于常见情况 — 发票、合同、收据、截图、干净的 PDF — 您可以在无需成本、无需设置的情况下获得云级提取，并且不会有任何文件离开您的机器。
## 隐私层
macos-vision-mcp 作为您的文档和云之间的本地预处理层。适用于：
- 法律文件、合同、NDA
- 财务报告、发票、内部电子表格
- 医疗记录或任何 GDPR 敏感内容
- 任何您希望在发送到上游之前本地提取结构化数据的情况
您不将原始文档发送到 AI，而是先在本地提取文本和结构。然后，模型仅处理提取的文本 — 而不是原始文件。
## 快速开始
**添加到您的 MCP 客户端（以 Claude Code 为例）：**
```sh
claude mcp add macos-vision-mcp -- npx -y macos-vision-mcp
```
使用 **Claude Desktop** 或 **Cursor**？ [跳转到配置 ↓](#配置)
重启您的客户端。`npx` 在第一次运行时会获取包，缓存它，工具会自动出现 — 无需单独的安装步骤。这是大多数 MCP 服务器使用的约定，得到 Anthropic、Cursor 等客户端的推荐。
> **注意：** 在第一次运行时，包会从 GitHub Releases 下载预构建的 Swift 帮助程序二进制文件（`vision-helper`、`pdf-helper`）（约 300 KB，约 1-2 秒）。后续调用会命中 npx 缓存并立即启动。Xcode 命令行工具仅在下载无法访问网络时作为备用 — 设置 `MACOS_VISION_SKIP_DOWNLOAD=1` 以使用 `swiftc` 进行本地编译。
> **优先使用即时冷启动（无 npx 缓存查找）？** 使用 `npm install -g macos-vision-mcp` 进行全局安装，并使用[配置](#配置)底部的替代配置。
## 可用工具
| 工具 | 功能 | 示例提示 |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `ocr_image` | 从图像或 PDF（JPG、PNG、HEIC、TIFF、PDF）中提取文本。返回纯文本，或每页段落 + 文本块，带有 `lineId` / `paragraphId` 和边界框。接受 `start_page` / `max_pages` 进行部分 PDF OCR。 | "从 ~/Desktop/screenshot.png 读取文本" |
| `detect_faces` | 检测人脸并返回其数量和位置。 | "有多少人出现在 photo.jpg 中？" |
| `detect_barcodes` | 读取 QR 代码、EAN、UPC、Code128、PDF417、Aztec 和其他 1D/2D 代码。 | "/tmp/qr.jpg 中的二维码内容是什么？" |
| `detect_document` | 检测照片中的文档（纸张、收据、身份证）的四个角点。有助于在 OCR 之前进行裁剪/去倾斜。 | "找到 ~/Desktop/receipt.jpg 中的文档角点" |
| `classify_image` | 将图像内容分类为 1000+ 个类别，并带有置信度分数。 | "这张图片是什么？" |
| `analyze_document` | 返回结构化 JSON，包含按阅读顺序的段落、原始文本块（边界框/置信度）、人脸、条形码和矩形 — 准备好让模型重建为 Markdown、HTML 或其他格式。同时接受 `start_page` / `max_pages` 进行长 PDF。 | "将 ~/Desktop/scan.pdf 重建为干净的 Markdown" |
## 用法
在提示中明确使用工具名称以保证本地处理：
**从图像或 PDF 中提取文本：**
```
使用 ocr_image 从 ~/Desktop/invoice.pdf 中提取文本
```
**在照片中检测人脸：**
```
在 ~/Photos/team.jpg 上使用 detect_faces 并告诉我有多少人
```
**分类图像内容：**
```
使用 classify_image 对 ~/Downloads/unknown.jpg 进行分类
```
**完整的文档分析和重建：**
```
使用 analyze_document 对 ~/Desktop/report.pdf 进行分析，并重建为干净的 Markdown
```
工具返回结构化的 JSON；模型选择您要求的输出格式（Markdown、HTML、DOCX 大纲等），无需任何额外依赖 — 无需 Ollama，无需云 LLM，无需额外工具。
## 示例工作流程
连接服务器后，开箱即用：
- **"将 PDF 转换为干净的 Markdown 供 LLM 使用"** — `analyze_document` 返回按阅读顺序的段落和边界框；模型渲染 Markdown 准备好放入文档网站、知识库或 RAG 管道中。
- **"在将发票数据发送到 GPT 之前本地提取"** — 使用 `analyze_document` 从 PDF 中提取行项目、总额、供应商和日期，然后仅发送结构化的 JSON 到上游。原始文档永远不会离开您的 Mac。
- **"扫描收据 → JSON → 费用跟踪器"** — 在手机照片上使用 `ocr_image`，模型规范化金额/日期/商家，并将结果直接导入费用工具的 API。
- **"从截图中解码二维码"** — `detect_barcodes` 返回解码值和符号学在一个往返中。
- **"裁剪纸张表单照片以进行 OCR"** — `detect_document` 返回四个角点，以便您（或下游工具）可以在读取文本之前裁剪和去倾斜图像。
### 输出模式（analyze_document）
```jsonc
{
"source": { "path": "...", "pageCount": 1, "isPdf": false },
"pages": [
{
"page": 0,
// 重建的主要表面 — 按阅读顺序的段落用 "\n" 连接
"paragraphs": [
{ "paragraphId": 0, "lineIds": [0], "text": "ACME COFFEE" },
{ "paragraphId": 1, "lineIds": [1, 2], "text": "12 Main St\nPortland, OR" },
],
// 空间回退 — 带有页面本地 0-1 边界框、置信度、行/段落隶属关系的原始块
"textBlocks": [
{
"text": "ACME COFFEE",
"lineId": 0,
"paragraphId": 0,
"confidence": 0.99,
"bbox": { "x": 0.21, "y": 0.04, "width": 0.58, "height": 0.06 },
},
],
"faces": [],
"barcodes": [],
"rectangles": [],
},
],
"summary": {
"totalTextBlocks": 8,
"totalParagraphs": 2,
"totalFaces": 0,
"totalBarcodes": 0,
"totalRectangles": 0,
},
}
```
使用 `paragraphs[].text` 进行 95% 的情况（直接重建 Markdown/HTML/纯文本）。当您需要空间上下文时，使用 `textBlocks[]` — 多列布局、表格、表单、ID。
**注意：**
- `ocr_image` 在 `blocks` 模式下返回相同的每页形状，但没有检测部分：`{ pages: [{ page, paragraphs, textBlocks }] }`。
- PDF 按页处理。所有坐标均为页面本地（0-1），`paragraphId` / `lineId` 在每页重置。
- PDF 上的面部、条形码和矩形检测是尽力而为的 — 底层二进制文件分析整个文件，而不是按页，因此返回的任何检测都仅附加到第 0 页。
## 配置
以下示例都使用 `npx -y` — 推荐的默认值。无需事先 `npm install`；包会在第一次运行时获取并缓存，更新会在 npx 缓存过期时自动拾取。
### Claude Code
```sh
claude mcp add macos-vision-mcp -- npx -y macos-vision-mcp
```
### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"macos-vision-mcp": {
"command": "npx",
"args": ["-y", "macos-vision-mcp"]
}
}
}
```
### Cursor
添加到 `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"macos-vision-mcp": {
"command": "npx",
"args": ["-y", "macos-vision-mcp"]
}
}
}
```
### 替代：全局安装
如果您希望在冷启动时跳过 npx 缓存查找 — 或您想固定特定版本 — 请全局安装一次：
```sh
npm install -g macos-vision-mcp
```
然后在上面的 JSON 配置中使用 `"command": "macos-vision-mcp"`（无 `args`），或对于 Claude Code，使用 `claude mcp add macos-vision-mcp -- macos-vision-mcp`。请注意，全局安装可能会在与 nvm / asdf / volta 切换 Node 版本时出现问题 — 切换后请重新运行 `npm install -g`。
## 支持
如果 macos-vision-mcp 为您节省了令牌或将文档保留在 Mac 上，请考虑 [点赞仓库](https://github.com/woladi/macos-vision-mcp) — 它帮助其他人找到它。
## 贡献
欢迎贡献。请遵循 [Conventional Commits](https://www.conventionalcommits.org/) 进行提交消息 — 该项目使用 `release-it` 和 `@release-it/conventional-changelog` 来自动化发布。
```sh
git clone <仓库>
cd macos-vision-mcp
npm install
npm run dev # 监视模式
```
## 许可证
MIT — Adrian Wolczuk
