AI导哈

macOS窗口截图服务

一个为AI编码代理设计的Model Context Protocol (MCP)服务器，支持按需捕获macOS窗口和显示器的截图。

  • by jasich
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 jasich/mac-vision-mcp

使用说明

mac视觉mcp

模型上下文协议（MCP）服务器，使AI编码代理能够捕获macOS窗口的屏幕截图并按需显示。

为什么

LLM在使用图像作为背景方面非常出色。您可以将图像文件馈送到LLM，它可以执行分析设计或读取文本等操作。我发现自己总是想向LLM“展示”我正在查看的内容，但我发现截图、查找文件和给出LLM的路径很麻烦。此外，我最终得到了 数千 随着时间的推移，我需要管理的截图。所以我想，为什么法学硕士不能自己做这件事呢？这就是导致这个项目的原因。

特性

  • 窗口发现 -列出所有打开的窗口及其元数据（标题、应用、边界、显示）
  • 窗口捕获 -按ID捕获特定窗口的屏幕截图
  • 显示捕捉 -捕获整个显示器（单个或全部）
  • 智能过滤 -自动过滤掉系统覆盖和实用程序窗口
  • 自然整合 -与任何兼容MCP的AI代理无缝协作
  • 隐私第一 -在Mac上完全本地运行
  • 专业测井 -带时间戳的结构化日志记录，用于调试

系统要求

  • macOS12.0+（蒙特利或更高）
  • 建筑：英特尔（x64）或苹果硅（arm64）
  • Node.js：16.0.0或更高
  • 权限：需要屏幕录制权限

安装

全局安装（推荐）

npm install -g mac-vision-mcp

与npx一起使用（无需安装）

npx -y mac-vision-mcp

快速开始

1.授予屏幕录制权限

首次运行时，macOS会提示您授予屏幕录制权限：

  1. 打开 系统首选项
  2. 首选 隐私和安全 > 屏幕录制
  3. 为运行MCP服务器的应用程序启用权限
  4. 重新启动MCP服务器

2.配置您的MCP客户端

克劳德代码

增添 .mcp.json 在您的项目中：

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

对于光标

增添 ~/.cursor/mcp.json:

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

适用于克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

3.与您的AI代理一起使用

配置后，您的AI代理可以使用自然语言捕获屏幕截图：

User: "Show me my Chrome window with the error"

Agent: [calls list_windows]
Agent: [calls capture_window with the Chrome window ID]
Agent: "I can see the 404 error in your browser..."

MCP工具

list_windows

使用元数据获取所有打开的窗口。

参数： 无

退货：

{
  "windows": [
    {
      "id": "12345",
      "title": "Chrome - Documentation",
      "app": "Google Chrome",
      "bounds": {
        "x": 0,
        "y": 23,
        "width": 1920,
        "height": 1057
      },
      "display": 0
    }
  ]
}

capture_window

捕获特定窗口的屏幕截图。

参数：

  • window_id （必填，字符串）-窗口ID来自 list_windows
  • mode （可选，字符串）-捕获模式： "full" 或 "content" （默认值： "full")
  • output_path （可选，字符串）-自定义输出路径（必须以结尾 .png)

退货：

{
  "success": true,
  "file_path": "/tmp/screenshot_12345.png",
  "window": {
    "id": "12345",
    "title": "Chrome - Documentation",
    "app": "Google Chrome"
  }
}

capture_windows

同时捕获多个窗口的屏幕截图。当您需要同时查看多个窗口时非常有用。

参数：

  • window_ids （必填，string[]）-来自的窗口ID数组 list_windows
  • mode （可选，字符串）-捕获模式： "full" 或 "content" （默认值： "full")
  • output_dir （可选，字符串）-自定义输出目录（默认：temp目录）

退货：

{
  "success": true,
  "captures": [
    {
      "window_id": "12345",
      "success": true,
      "file_path": "/tmp/screenshot_12345.png",
      "window": {
        "id": "12345",
        "title": "Chrome - Documentation",
        "app": "Google Chrome"
      }
    },
    {
      "window_id": "67890",
      "success": true,
      "file_path": "/tmp/screenshot_67890.png",
      "window": {
        "id": "67890",
        "title": "VS Code",
        "app": "Code"
      }
    }
  ]
}

capture_display

捕获整个显示器。

参数：

  • display_id （可选，数字）-特定显示数字（0索引），或省略以捕获所有

单显示器返回：

{
  "success": true,
  "file_path": "/tmp/display_0.png",
  "display": 0
}

所有显示器返回：

{
  "success": true,
  "captures": [
    {
      "display": 0,
      "file_path": "/tmp/display_0.png"
    },
    {
      "display": 1,
      "file_path": "/tmp/display_1.png"
    }
  ]
}

故障排除

权限被拒绝错误

错误： Screen Recording permission required

解决方案：

  1. 打开系统首选项>隐私和安全>屏幕录制
  2. 为您的终端或应用程序启用权限
  3. 重新启动MCP服务器

未找到窗口

错误： Window {id} not found. It may have been closed.

原因： 在上市和收购之间，窗口是关闭的。

解决方案： 呼叫 list_windows 再次获取当前窗口ID。

输出路径无效

错误： Output path must end with .png

解决方案： 确保自定义输出路径具有 .png 扩展。

本机模块问题

错误： 本机模块编译错误

解决方案：

  1. 确保您使用的是macOS 12.0+
  2. 验证Node.js版本是否为16.0.0+
  3. 尝试重新安装： npm install -g mac-vision-mcp --force

未列出Windows

问题： list_windows 返回空数组或缺少窗口

原因： 未授予屏幕录制权限或已筛选出窗口

解决方案：

  1. 验证是否启用了屏幕录制权限
  2. 注意：系统窗口和手势覆盖会自动过滤
  3. 小于50x50像素的窗口除外

建筑

  • 语言：带有ESM模块的Types/Node.js
  • MCP-SDK：@modelcontextprotocol/sdk（v1.22.0）
  • 屏幕截图库：具有本机N-API绑定的节点屏蔽主机（v0.2.4）
  • 窗口元数据：获取窗口（v9.2.3）
  • 权限：mac屏幕截图权限（v2.1.0）
  • 验证：Zod（v3.25.0）

发展

本地设置

# Clone repository
git clone https://github.com/jasich/mac-vision-mcp.git
cd mac-vision-mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js

在另一个项目中使用本地构建

要使用Claude Code或其他MCP客户端测试您的本地开发版本：

  1. 构建项目 （如果尚未完成）：

    cd /path/to/mac-vision-mcp
npm run build

  2. 配置其他项目的 .claude.json 使用绝对路径：

    {
  "mcpServers": {
    "mac-vision": {
      "command": "node",
      "args": ["/path/to/mac-vision-mcp/dist/index.js"]
    }
  }
}

  3. 重新启动Claude代码 加载本地构建

  4. 进行更改和重建 根据需要：

    npm run build  # Rebuild after code changes

注： 替换 /path/to/mac-vision-mcp 与您实际的项目绝对路径。

MCP检验员测试

# Run with MCP Inspector for debugging
npx @modelcontextprotocol/inspector node ./dist/index.js

贡献

欢迎投稿！请随时提交问题或拉取请求。

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

致谢

支持

  • 问题：通过GitHub Issues报告错误或请求功能
  • 文档: 模型上下文协议文档
  • MCP检查员：用于测试和调试MCP工具

相关 MCP