macos-vision-mcp

macos-vision-mcp

_{你的文档和屏幕都留在本机。只有提取出的文本和结构化 JSON 会传给模型。}

适用于任何 MCP 客户端的本地、私密、离线 OCR 和 UI 测试——无需 API 密钥，无需上传。 将文档 Token 成本降低约 97%，并让 Agent 查看和点击 Mac 的 UI，整个过程无需将任何截图传出本机。

在 AI 查看内容之前，先在本地预提取文本和图像数据——在真实文档上可将 Token 用量降低约 97%，并返回结构化的段落、行和边界框，让模型能够将文档还原为 Markdown、HTML、DOCX 或任何其他格式。文件绝不会离开你的 Mac：无需云端 API，无需 API 密钥，也不会发起网络请求。

_{**约 97% 的测量方式：**将一份 44 页的扫描 PDF 作为页面图像发送，成本约为 73,500 个 Token；对同一文件运行 analyze_document，会返回约 2,400 个 Token 的提取文本和结构（原始页面图像 Token 与提取文本 Token 的对比）。具体数值会因页面密度和分词器而异——请将 97% 视为大致量级，而非保证值。}

目录： 快速开始 · 你将获得什么 · Agent 的用途 · UI 测试 · 有何不同 · 可用工具 · 用法 · 工作流示例 · 配置 · 隐私层

你将获得什么

• 通过 Apple Vision Framework 对图片和 PDF 进行 OCR（JPG、PNG、HEIC、TIFF、多页 PDF）。
• 减少约 97% 的 token：44 页 PDF 约需 2,400 个 token，而非约 73,500 个。
• 按阅读顺序排列的段落和带边界框的原始文本块——为模型提供丰富的结构，以便将文档重构为任意输出格式（Markdown、HTML、DOCX、JSON），而不是有损的纯文本转储。
• 人脸检测、条形码/QR 码读取和图像分类——全部在设备本地完成。
• 完整的文档处理流程：通过一次工具调用完成 OCR、人脸检测、条形码检测和矩形检测。
• 适用于 Claude Code、Claude Desktop 和 Cursor——以及任何兼容 MCP 的客户端。
• 不会将文件上传到任何服务端——处理完全在你的 Mac 上进行。
• 面向 Agent 的 UI 测试：在本地截取窗口，按可见文本查找元素，获取点击坐标，并断言屏幕上显示的内容——全程无需上传截图。
• npm install 后可 100% 离线运行——由 Apple Vision Framework 提供支持，与 Photos.app 中的实时文本使用相同引擎。

❌ 不使用 / ✅ 使用

❌ 不使用 macos-vision-mcp：

• 发送一份 44 页的 PDF 需要约 73,500 个 token
• 每张图片、每张发票或每份合同都要经过云端 API
• 每次请求都会将敏感文档传出你的设备

✅ 使用 macos-vision-mcp：

• Apple Vision 在本地预先提取文本，Claude 才会看到内容
• 同一份 44 页 PDF 约需 2,400 个 token——减少 97%
• 文件永远不会离开你的 Mac

Agent 如何使用它

Agent 在 Mac 上执行的大多数工作都不需要深入理解布局。它只需查看屏幕内容、找到目标、执行操作，并确认结果。这个循环—— list_windows → find_element → 点击（通过任意输入驱动程序）→ assert_text——适用于许多场景， 而且每一步都在本机上运行。

• 操作没有 API 的应用。 原生工具、Electron 应用、内部软件，以及任何有 GUI 但没有脚本接口的软件。find_element("Export") 会返回可点击的位置。
• 读取当前屏幕上的内容。 对话框、错误横幅、通知、进度状态——包括被其他窗口遮挡的窗口，无需将其置于最前方。
• 确认操作是否真正成功。 assert_text 会在 Unicode 规范化后进行字符串匹配，因此每次都能以相同方式返回通过/失败结果，而不是让模型判断图片。
• 从无法导出数据的软件中提取信息。 对窗口进行 OCR、获取文本，然后继续操作。
• 审计无障碍功能。 ui_snapshot 会报告无障碍树未涵盖的所有可见文本——包括未标注的控件和自绘文本，并附带坐标。
• 测试 UI 是否出现回归。 这个项目最初就是为此而开发的，现在仍然适用——见下文对应章节。
• 处理文档。 最初的用途：发票、合同、扫描件和 PDF。

为什么在本地处理更好，而不只是不同

更省钱。 一次判定约消耗 240 个令牌，而它替代的截图约消耗 6,900 个令牌——便宜约 29 倍。对于一个包含 20 个步骤的任务，消耗约为 4,800 个令牌，而不是约 138,000 个。这意味着 Agent 可以在每一步后检查自己的工作，而不是无力这样做。

隐私性更好，而且这部分不会体现在账单上。 截图并不是你关心的按钮的整洁裁剪图。它还会包含屏幕上的其他内容：另一个窗口、密码管理器、打开的收件箱、客户记录。将截图发送给第三方是一种无法撤回的信息披露，而且每一步都会重复。在这里，图像会写入临时文件，由 Neural Engine 上的模型读取，绝不会序列化到对话中。这一不变量由代码保证，而不是在本 README 中作出承诺：没有任何工具会返回图像字节。

实际使用更快，而且更稳定，而稳定性更重要。 在 M1 Pro 上，find_element 的端到端耗时为 1.17–1.25 秒——截屏耗时 0.31–0.41 秒，OCR 耗时约 1.04 秒，匹配不到 1 毫秒。整个过程完全没有网络耗时：推理开始前无需上传约 750 KB 的数据，没有速率限制，没有服务提供方负载过高的问题，也不会因 Wi-Fi 中断而失败。无论在飞机上还是在办公桌前，同一次调用的耗时都相同。

它不会做什么：点击。 它是眼睛，不是双手，因此绝不会要求控制你的机器。你可以搭配输入驱动程序使用——例如 cliclick、类似 macos-mcp 的自动化服务，或任何接受屏幕坐标的工具——并将 find_element 返回的 clickPoint 交给它。这样的分工是刻意设计的：观察和操作需要不同的权限，而此服务只会请求前者。

无需向任何地方发送截图的 UI 测试

通常，让 Agent 操作 GUI 的方法是截取屏幕并将其上传到视觉模型。每一步都意味着一次网络往返、一次图像令牌费用，以及一份屏幕内容副本。一个包含 10 个步骤的流程就意味着要上传 10 次桌面截图。

此服务会在本地完成视觉识别。Apple 的 Vision 框架运行于 Neural Engine，因此截图会保留在磁盘上，只有文本、几何信息和判定结果会传给模型。

_{Agent 实际收到的内容。 元素框、角色和标签——均经测量而非猜测——以及准确的点击位置。截图本身绝不会离开 Mac。}

find_element(query: "Save", app: "MyApp")
  → { found: true, matches: [{ text: "Save", method: "exact",
        clickPoint: { x: 812, y: 556 }, bbox: {...} }] }

# hand clickPoint to any input driver — macos-mcp, cliclick, CGEvent
# then verify, again locally:

assert_text(expect: "Saved", app: "MyApp")  → { pass: true, ... }

clickPoint 使用全局屏幕坐标，原点位于左上角——与点击驱动程序使用的坐标空间相同，因此可直接传给驱动程序，无需转换。此服务刻意不执行点击：它是眼睛，不是双手，因此绝不会要求控制你的机器。

真的更便宜、更安全、更快吗？

在 Apple M1 Pro（2021 年，16 GB） 上，针对一个真实的、文字密集型应用进行测试，截取 2992×1734 的 Retina 窗口画面——每项测试运行五次后取中位数。

	本地（此服务）	截图 → 云端视觉 API
每步 Token 数	~240（一次 assert_text 判定）	~6,900（2992×1734 图像的 Token 数）
离开 Mac 的数据	无	每步上传约 750 KB 的屏幕 PNG
网络	无——离线、在飞机上或处于网络隔离环境时均可运行	每步需一次往返
延迟	find_element 端到端耗时 1.17–1.25 秒	上传 + 推理 + 返回
成本	$0	每张图片、每一步都要付费，且永远如此

_{图像 Token 数根据 Anthropic 的 width × height / 750 规则估算；其他提供商采用不同的分块方式，因此具体数字会变化，但数量级不变。本地 Token 数是工具实际返回的 JSON 载荷，按每个 Token 约 4 个字符计算。}

_{同一个问题，同一个答案，价格约为 29 倍。在 M1 Pro 上针对 2992×1734 的窗口截图进行测量。}

支撑这张表格的三项主张——更便宜、更安全、更快——已在上文的Agent 会用它做什么中论述。本节补充的是实测数据：这些数字是在 Apple M1 Pro（2021 年，16 GB）上，针对真实、文字密集型窗口的 2992×1734 Retina 截图运行五次后取中位数得出的。

我们尚未对任何特定视觉提供商进行基准测试，因此右侧一栏应视为对比结构，而非实测数据。可以确定的是，本地路径不受带宽、速率限制或提供商负载波动的影响，网络故障时也不会因此失败。

还有两个需要如实说明的注意事项。只对单个区域进行定位，而不是整个窗口，可显著降低 OCR 开销，因为成本随搜索像素数变化。安装后的首次调用需要约 2 秒来编译一个小型 Swift 助手程序；之后的每次调用都已完成预热。

它擅长什么，以及不擅长什么

擅长：原生 macOS 应用、无障碍支持较差的 Electron 应用、画布/WebGL 界面、游戏和设计模型——任何没有 DOM 可供查询的场景。也适合需要确定性断言，而不是模型主观判断的情况：assert_text 会在 Unicode 规范化后进行字符串匹配，因此每次都会返回相同的答案。

对于普通网页来说，这不是合适的工具：Playwright 或 DOM 在这类场景下会更快、更精确。而且 OCR 只能识别渲染出来的内容，因此无法读取控件的 enabled 状态或其无障碍角色。

比较前会先对文本进行规范化处理——使用 NFC、折叠空白字符，并统一 Unicode 破折号和引号——然后依次尝试精确匹配 → 子串匹配 → 模糊匹配（Levenshtein）。匹配被拒绝时，仍会在 nearMisses 下报告，因此可以区分“标签确实存在，但 OCR 将 Zapisz 读成了 Zapisr”和“标签确实不存在”。

对子串命中会按匹配质量评分，而不是一视同仁：查询词若位于单词边界、匹配到标签开头，且覆盖标签的比例更高，得分就更高。当要找的是按钮时，这种排序很重要——对于查询 Save，Save Changes 必须排在 Don't Save 之前。每个匹配结果都会报告 wholeWord，而 assert_text 只会根据该值为 true 的匹配结果判定：Unsaved changes 中的 Save 只是拼写上的巧合，既不能证明屏幕上有 Save 按钮，也不能证明它不在屏幕上。这类命中仍会列在 incidental 下。

要求

• 为托管 MCP 服务的应用（Terminal、Claude Desktop、Cursor）授予屏幕录制权限：前往“系统设置”→“隐私与安全性”→“屏幕录制”，然后重启该应用。 无需编译器或 Xcode 工具——原生辅助程序已预先构建完成。

  授权针对的是宿主进程，而不是软件包：同一个服务可能在一个客户端中完全正常，却在同一台 Mac 上的另一个客户端中无法识别屏幕。缺少权限时，捕获会直接失败，macOS 还会同时隐藏所有窗口标题，因此 list_windows 会为所有窗口返回 title: ""——这种情况会标记为 titlesAvailable: false，而不是让人误以为屏幕上全是没有标题的窗口。请先运行 vision_capabilities：ready 和 blockers 会说明当前哪些功能可用。

• Mac 必须处于解锁状态。锁定时，窗口和区域捕获会直接失败，全屏捕获则只会返回锁屏画面；vision_capabilities 会报告 screenLocked，以便 Agent 在开始前检查，而不是事后猜测失败原因。

与众不同之处

大多数面向 LLM 的 OCR 方案，要么会把文档发送到云端视觉 API，要么需要你自行搭建并调优引擎。本工具运行在 Apple 的设备端 Vision 框架上——这也是 Photos.app 中「实况文本」背后的同一引擎——因此提取内容免费、私密且即时。

	macos-vision-mcp	云端视觉 OCR（GPT-4o、Google Vision、Mistral OCR）	基于 Tesseract 的 MCP
费用	$0 — 不按页数或 token 收费	按调用次数／页数计费	$0，但需自行托管
离线使用	是，安装后即可	否 — 每页都需要联网	是
隐私	文件不会离开你的 Mac	文档会上传给第三方	本地
设置	一条命令，无需密钥	API 密钥 + 计费账户	安装 + 语言数据 + 调优
质量	Apple Vision（擅长处理清晰扫描件、收据和屏幕截图）	整体较高	因情况而异；处理质量较差的扫描件时表现较弱
UI 测试	内置 — 截取、定位、断言，无需上传	可以实现，但每一步都会上传屏幕	仅 OCR；无法截取或定位

需要坦诚说明取舍：它仅支持 macOS，而且对于严重倾斜或对比度较低的扫描件，云端模型可能仍能读取更多内容。对于常见场景——发票、合同、收据、屏幕截图和清晰的 PDF——你可以零成本、零配置地获得媲美云端的内容提取效果，且无需将任何内容传出设备。

隐私层

macos-vision-mcp 作为文档与云端之间的本地预处理层。适用于：

• 法律文件、合同、保密协议
• 财务报告、发票、内部电子表格
• 医疗记录或任何涉及 GDPR 敏感内容的资料
• 任何你想先在本地提取结构化数据，再决定是否要将内容发送到上游的场景

你可以先在本地提取文本和结构，而不是把原始文档发送给 AI。随后，模型只会处理提取出的文本，绝不会接触原始文件。

屏幕也一样。即使只是为了一项小检查而截取屏幕，图像中仍可能包含当时可见的其他所有内容——其他窗口、密码管理器、客户记录、打开的收件箱。UI 测试工具会将图像保存在磁盘上，只返回路径、几何信息和文本，因此 UI 断言不会造成意外泄露。本服务中的任何工具都不会向模型返回图像字节。

快速开始

添加到你的 MCP 客户端（以 Claude Code 为例）：

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、ui-helper、ax-helper）（压缩后约 276 KB，约需 1–2s）。之后的调用会使用 npx 缓存并立即启动。只有在下载无法连接网络时，才需要 Xcode Command Line Tools 作为备用方案——设置 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	检测人脸，并返回数量和位置。	“这张照片里有几个人？”
detect_barcodes	读取 QR 码、EAN、UPC、Code128、PDF417、Aztec 以及其他一维/二维代码。	“/tmp/qr.jpg 中的 QR 码写了什么？”
detect_document	检测照片中单份文档（纸张、收据、证件）的四个角点。可在 OCR 前用作裁剪 / 校正倾斜的参考。	“查找 ~/Desktop/receipt.jpg 中的文档角点”
classify_image	将图像内容分类到 1000 多个类别，并提供置信度分数。	“这张图里有什么？”
analyze_document	返回结构化 JSON，包含按阅读顺序排列的段落、原始文本块（bbox / 置信度）、人脸、条形码和矩形，便于模型重建为 Markdown、HTML 或其他格式。也支持使用 start_page / max_pages 处理较长的 PDF。	“将 ~/Desktop/scan.pdf 重建为简洁的 Markdown”

UI 测试工具（本地运行，不会向云端发送屏幕截图）

这些工具让 Agent 查看并验证 Mac 的 UI，全程不会向云端模型发送屏幕截图。屏幕截图在本地捕获，OCR 在设备上运行，只会返回路径、几何信息和提取的文本。find_element 会提供屏幕点坐标，可直接交给任何输入驱动程序（此 MCP 服务刻意不执行点击——只负责观察，不负责操作）。

工具	功能	示例提示词
capture_screen	截取主显示器、窗口（即使被遮挡）、应用的最前端窗口或某个区域的屏幕截图。返回文件路径和屏幕点坐标系中的边界框，不会返回图像字节。	“截取 Safari 窗口”
list_windows	按从前到后的顺序列出屏幕上的窗口及其全局屏幕点坐标边界。	“有哪些窗口处于打开状态？”
read_screen_text	一步完成捕获和 OCR，完全离线读取应用当前显示的内容。	“TestFlight 窗口上写了什么？”
find_element	根据可见文本查找 UI 元素；返回全局屏幕点坐标系中的 clickPoint {x,y}（依次进行精确匹配、子串匹配和模糊匹配，并报告近似匹配结果）。	“MyApp 中的保存按钮在哪里？”
assert_text	在本地断言屏幕上是否存在或不存在某段文本，并返回通过或失败结果——由 Mac 本机计算，而非云端模型。	“点击保存后，验证对话框中是否显示 ‘Saved’”
vision_capabilities	报告 macOS 版本、屏幕录制和辅助功能权限状态，以及显示器信息。	“这台机器能运行 UI 测试吗？”
ui_snapshot	以 JSON 格式返回完整布局：从辅助功能树中获取每个元素的精确边界框、角色、标签和状态，可选包含颜色和字体；还会返回树中未记录的可见文本。	“检查此对话框的布局” · “哪些元素没有标签？”

MCP 服务所在应用（Terminal / Claude Desktop / Cursor）需要获得屏幕录制权限：前往“系统设置”→“隐私与安全性”→“屏幕录制”，然后重启该 应用。无需安装其他内容——原生辅助程序已随 macos-vision 预先构建。

ui_snapshot — 布局，而不只是文本

find_element 回答“X 在哪里”。ui_snapshot 回答“此屏幕上有什么”：每个元素的实测框（来自辅助功能 API，而非根据 OCR 推断）、其角色、标签和启用状态、父子结构，以及可选的从捕获图像中采样的颜色和真实字体数据。

{
  "app": "MyApp",
  "window": [0, 29, 1496, 867],
  "source": "ax+px",
  "budget": { "elements": 289, "walked": 400, "capped": false, "elapsedMs": 136 },
  "nodes": [
    {
      "id": 42,
      "parent": 7,
      "role": "Button",
      "label": "Zapisz",
      "box": [812, 540, 96, 32],
      "style": { "bg": "#2F6FEB", "border": "#1B4FC4", "borderWidth": 1 },
      "text": { "font": "SFPro-Semibold", "size": 13, "align": "center" },
    },
  ],
  "unresolved": [{ "text": "Sprzedaż Q4", "box": [420, 300, 88, 16], "coveredByNode": 17 }],
  "summary": {
    "nodes": 289,
    "labelled": 240,
    "ocrBlocks": 123,
    "unresolved": 21,
    "axTextCoverage": 0.83,
  },
}

unresolved 是 Vision 能读取但没有辅助功能节点对应的文本。它补全了 AX 看不到的内容——画布、WebGL、游戏、嵌入图像中的文本——每个条目都代表应用中的一个辅助功能缺口：存在 coveredByNode 表示有控件但未标注；不存在则表示完全没有暴露任何内容。

请正确解读：budget.capped 表示树不完整，此时 summary.axTextCoverage 会有意设为 null——遍历受限时，衡量的是已访问的内容，而不是应用的辅助功能状况。颜色来自像素，因此被遮挡的元素会报告覆盖其上的内容所绘制的颜色；borderWidth 是推断值，且没有内边距或外边距。这不是 CSS 盒模型。

除屏幕录制权限外，还需要辅助功能权限，并且 Mac 必须处于解锁状态——锁定的屏幕不会暴露任何辅助功能窗口。

用法

在提示词中明确指定工具名称，以确保在本地处理：

从图像或 PDF 中提取文本：

Use ocr_image to extract text from ~/Desktop/invoice.pdf

检测照片中的人脸：

Use detect_faces on ~/Photos/team.jpg and tell me how many people are in it

对图像内容进行分类：

Use classify_image on ~/Downloads/unknown.jpg

完整的文档分析与重建：

Use analyze_document on ~/Desktop/report.pdf and reconstruct it as clean Markdown

该工具会返回结构化 JSON；模型会按你要求的格式（Markdown、HTML、DOCX 大纲等）选择输出，无需任何额外依赖——不需要 Ollama、云端大模型或其他工具。

示例工作流

连接服务后即可直接使用的真实场景组合：

• “将 PDF 转换为适用于大模型的简洁 Markdown” — analyze_document 会返回按阅读顺序排列的段落和边界框；模型会生成 Markdown，可直接放入文档站点、知识库或 RAG 流程。
• “在发送给 GPT 之前，在本地提取发票数据” — 使用 analyze_document 在本地从 PDF 中提取明细项、总额、供应商和日期，然后只将结构化 JSON 发送到上游。原始文档不会离开你的 Mac。
• “扫描收据 → JSON → 费用追踪工具” — 对手机拍摄的照片使用 ocr_image，由模型规范金额 / 日期 / 商户信息，并将结果直接传入费用工具的 API。
• “从截图中解码 QR 码” — detect_barcodes 一次调用即可返回解码后的值和码制。
• “在 OCR 前裁剪纸质表单照片” — detect_document 会返回四个角点，以便你（或下游工具）在读取文本前校正倾斜并裁剪图像。
• “点击我应用中的 Save 按钮” — find_element 会返回以屏幕点为单位的 clickPoint；将其交给点击驱动程序（macos-mcp、cliclick）即可。截图不会离开 Mac。
• “检查我的应用在这次更改后是否仍能正确渲染” — assert_text 可以确定性地判断屏幕内容是否符合预期；每次检查约消耗 240 个 token，而截图约需 6,900 个。
• “读取那个后台窗口中的错误消息” — read_screen_text 可以捕获指定窗口（即使该窗口被其他窗口遮挡），并仅返回文本。
• “我的应用现在显示什么？” — 使用 list_windows 选择目标窗口，再用 read_screen_text 读取，无需将窗口置于最前面。

输出架构（analyze_document）

{
  "source": { "path": "...", "pageCount": 1, "isPdf": false },
  "pages": [
    {
      "page": 0,
      // primary surface for reconstruction — reading-order paragraphs joined with "\n"
      "paragraphs": [
        { "paragraphId": 0, "lineIds": [0], "text": "ACME COFFEE" },
        { "paragraphId": 1, "lineIds": [1, 2], "text": "12 Main St\nPortland, OR" },
      ],
      // spatial fallback — raw blocks with page-local 0–1 bbox, confidence, line/paragraph membership
      "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,
  },
}

95% 的情况下，使用 paragraphs[].text（直接重建 Markdown/HTML/纯文本）。需要空间上下文时（多栏布局、表格、表单、ID），再使用 textBlocks[]。

注意：

• blocks 模式下的 ocr_image 返回相同的逐页结构，但不包含检测部分：{ pages: [{ page, paragraphs, textBlocks }] }。
• PDF 会逐页处理。所有坐标均为页面局部坐标（0–1），且 paragraphId / lineId 会在每页重置。
• PDF 中的人脸、条码和矩形检测只能尽力而为——底层二进制程序会分析整个文件，而不是逐页分析，因此返回的任何检测结果都只会附加到第 0 页。
• 段落分组使用空间启发式方法。对于多栏布局（杂志跨页、带侧边栏的 wiki 页面），启发式方法可能会将整页合并为单个段落。遇到这种情况时，请改用 textBlocks[]，并根据边界框重建内容。

配置

以下示例均使用 npx -y，这是推荐的默认方式。无需预先运行 npm install；首次运行时会获取并缓存软件包，之后会在 npx 缓存更新时自动获取更新。

Claude Code

claude mcp add macos-vision-mcp -- npx -y macos-vision-mcp

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "macos-vision-mcp": {
      "command": "npx",
      "args": ["-y", "macos-vision-mcp"]
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "macos-vision-mcp": {
      "command": "npx",
      "args": ["-y", "macos-vision-mcp"]
    }
  }
}

替代方案：全局安装

如果你不想在冷启动时查询 npx 缓存，或者想固定特定版本，可以安装一次：

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 为你节省了 token，或帮你将文档保留在 Mac 上，不妨考虑为仓库点个星——这有助于其他人找到它。

贡献

欢迎贡献。请在提交消息中遵循 Conventional Commits 规范。

版本发布使用 changesets。如果你的更改会影响用户，请在 PR 中添加 changeset：

npm run changeset   # pick patch / minor / major, describe the change

合并到 master 后，会创建一个“version packages” PR，用于更新版本、server.json 和变更日志；合并该 PR 后，会发布到 npm（使用 Trusted Publishing，并附带来源证明）、标记此版本，并刷新 MCP 注册表条目。

git clone <repo>
cd macos-vision-mcp
npm install
npm run dev   # watch mode

许可证

MIT — Adrian Wolczuk