macos-vision-mcp 是一个面向 MCP 客户端的本地离线 OCR 与图像分析服务器，基于 Apple Vision 框架运行，适用于 Claude Code、Claude Desktop、Cursor 等 MCP 兼容客户端。其目标是让文档和屏幕内容留在本机，仅将提取出的文字和结构化 JSON 发送给模型。
用途方面，它主要用于在本地预处理图片和 PDF 中的文字与结构信息，降低发送给模型的 token 消耗，并避免敏感文档离开 Mac。同时提供 UI 测试能力，让智能体无需上传截图即可查看屏幕、查找元素、获取点击坐标并断言屏幕文字。
主要能力包括：对 JPG、PNG、HEIC、TIFF 及多页 PDF 进行 OCR；返回阅读顺序的段落、原始文本块及边界框；支持人脸检测、条形码/二维码读取和图像分类；可在一次工具调用中完成 OCR、人脸、条形码和矩形检测的完整文档流水线。官方称，44 页扫描 PDF 作为页面图像发送约需 73,500 token，而通过 analyze_document 返回的提取文字与结构约 2,400 token，约减少 97%。
使用方式方面，需将服务器添加到 MCP 客户端，示例为 Claude Code 配置。首次运行 npx 会下载包并缓存，工具自动出现，无需单独安装步骤。首次运行还会从 GitHub Releases 下载预构建的 Swift 辅助二进制文件（vision-helper、pdf-helper、ui-helper、ax-helper，约 276 KB 压缩，约 1–2 秒）。后续调用使用 npx 缓存，启动迅速。仅当下载无法联网时，才需要 Xcode Command Line Tools 作为回退，可设置 MACOS_VISION_SKIP_DOWNLOAD=1 强制使用 swiftc 本地编译。若希望冷启动更快，可全局安装 npm install -g macos-vision-mcp 并使用替代配置。
适用场景包括：处理法律文件、合同、保密协议；财务报告、发票、内部表格；医疗记录或任何 GDPR 敏感内容；以及需要在本地提取结构化数据后再决定是否上传的场合。UI 测试方面适用于无 API 的原生 macOS 应用、Electron 应用、内部软件、画布/WebGL 界面、游戏和设计稿等没有 DOM 可查询的场景，也适合需要确定性断言而非模型主观判断的场合。
限制方面：仅支持 macOS；在严重倾斜或低对比度扫描件上，云端模型可能识别更好；不适合普通网页，Playwright 或 DOM 会更快更精确；OCR 只能看到已渲染内容，无法读取控件的启用状态或无障碍角色；它本身不执行点击，只提供视觉信息，需要搭配输入驱动（如 cliclick 或接受屏幕坐标的自动化服务器）使用返回的 clickPoint。
权限与运行条件：需要为承载 MCP 服务器的应用（如 Terminal、Claude Desktop、Cursor）授予屏幕录制权限，路径为系统设置 → 隐私与安全性 → 屏幕录制，然后重启该应用。无需编译器或 Xcode 工具，原生辅助程序为预构建。权限按宿主进程授予，而非按包。未授权时捕获会失败，且 macOS 会隐藏所有窗口标题，list_windows 对每个窗口返回 title: ""，并以 titlesAvailable: false 标记。建议先运行 vision_capabilities 查看 ready 和 blockers。需要 Mac 处于解锁状态；锁定状态下窗口和区域捕获会失败，全屏捕获仅返回锁屏，vision_capabilities 会报告 screenLocked。
隐私方面：文件不会离开 Mac，无云 API、无 API 密钥、无网络请求；UI 测试时截图写入临时文件，由 Neural Engine 上的模型读取，不会序列化到对话中，且没有任何工具向模型返回图像字节。
文本匹配在比较前会进行规范化（NFC、折叠空白、统一 Unicode 破折号和引号），然后依次尝试精确、子串和模糊（Levenshtein）匹配。被拒绝的匹配会列在 nearMisses 下。子串命中会分级评分，整体词匹配的命中会在 wholeWord 中报告，assert_text 仅依据 wholeWord 为 true 的匹配做出判定，其他命中列在 incidental 下。
