Peekaboo

🚀 Peekaboo MCP：极速截图，宛如超自然体验

Peekaboo MCP 是一款 macOS 实用工具，它能像幽灵般迅速捕捉屏幕快照，并借助超自然的 AI 视觉洞察窗口内容。它赋予 AI 助手真正的视觉能力，让它们能像人类一样“看到”你所描述的内容，从而在 bug 排查、设计审查、数据可视化分析等场景中发挥重要作用。

🚀 快速开始

需求

• macOS 14.0+（Sonoma 或更高版本）
• Node.js 20.0+

快速启动

将 Peekaboo 集成到你的 Agent 环境中：

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/peekaboo-mcp@beta"
      ],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "ollama/llava:latest"
      }
    }
  }
}

4. 重启 Claude Desktop

完成以上步骤后，Peekaboo 就会从数字世界中“现身”，准备好为你服务啦！👻

✨ 主要特性

为 AI 赋予视觉能力

• 🐛 精准定位 Bug：让 AI 能直观看到布局问题，快速定位 bug。
• 📸 即时分析：一键截图并提出问题，AI 即刻分析。
• 🎨 设计审查：AI 依据可视化证据评估你的 CSS 设计。
• 📊 数据洞察：AI 能解读图表数据，提供深入分析。
• 🖼️ UI 测试：确保应用在不同设备上显示正常，避免“在我电脑上正常”的问题。
• 📱 多屏捕获：随时捕获任意窗口、应用的屏幕内容。
• 🤖 自动化操作：让 AI 看到你所看到的，自动修复问题。

超自然的视觉捕获能力

• 多屏独立捕获：分别捕获每个显示屏的内容。
• 精准窗口定位：通过模糊匹配精准定位应用或窗口。
• 多种格式支持：支持 PNG、JPEG、WebP、HEIF 等多种图像格式。
• 智能命名规则：提供临时文件名和描述性命名。
• 权限自动检测：自动验证屏幕录制权限。

强大的管理功能

• 应用全面统计：列出所有运行的应用程序及其详细信息。
• 窗口精准查询：查询每个应用的窗口信息和元数据。
• 灵活匹配方式：通过部分名称、Bundle ID 或进程 ID 匹配应用。
• 状态实时监控：监控应用的活动状态和窗口数量。

广泛的 AI 集成

• 多 AI 支持：支持 Ollama 和 OpenAI，未来计划支持 Anthropic 等更多 AI 服务。
• 图像智能分析：通过自然语言查询分析捕获的图像内容。
• 灵活配置选项：通过环境变量选择 AI 提供商。

📦 安装指南

安装 Ollama

macOS（通过 Homebrew）

brew install ollama

你也可以访问 ollama.ai 下载 macOS 应用。

启动 Ollama 服务：

ollama serve

默认情况下，服务将在 http://localhost:11434 运行。

下载视觉模型

高性能设备推荐：LLaVA（Large Language and Vision Assistant）

# 下载最新版本的 LLaVA 模型（推荐）
ollama pull llava:latest

# 其他版本的 LLaVA 模型
ollama pull llava:7b-v1.6
ollama pull llava:13b-v1.6  # 更大、功能更强
ollama pull llava:34b-v1.6  # 最大、性能最强（需要大量内存）

低性能设备推荐：Qwen2-VL

# 下载 Qwen2-VL 7B 模型（性能与质量的平衡之选）
ollama pull qwen2-vl:7b

模型大小参考：

• qwen2-vl:7b - 约 4GB 下载，约 6GB 内存要求（适合低配置设备）
• llava:7b - 约 4.5GB 下载，约 8GB 内存要求
• llava:13b - 约 8GB 下载，约 16GB 内存要求
• llava:34b - 约 20GB 下载，约 40GB 内存要求

配置 Peekaboo 与 Ollama

将 Ollama 配置到 Claude Desktop 中：

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/peekaboo-mcp@beta"
      ],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "ollama/llava:latest"
      }
    }
  }
}

低性能设备配置（使用 Qwen2-VL）：

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/peekaboo-mcp@beta"
      ],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "ollama/qwen2-vl:7b"
      }
    }
  }
}

多 AI 提供商配置（Ollama + OpenAI）：

{
  "env": {
    "PEEKABOO_AI_PROVIDERS": "ollama/llava:latest,openai/gpt-4o",
    "OPENAI_API_KEY": "your-api-key-here"
  }
}

测试 Ollama 集成

验证 Ollama 是否正常运行：

# 检查 Ollama 服务状态
curl http://localhost:11434/api/tags

# 直接使用 Peekaboo 进行截图测试
./peekaboo image --app Finder --path ~/Desktop/finder.png

# 直接使用 Peekaboo 进行截图和分析测试（需要设置 PEEKABOO_AI_PROVIDERS 环境变量）
# 注意：CLI 本身不支持输入问题，这是 MCP 服务器的功能。
# MCP 服务器会先调用：./peekaboo image ... 获取图像
# 然后根据输入的问题调用 AI 提供商进行分析

授予必要权限

Peekaboo 需要以下 macOS 权限才能正常工作：

1. 屏幕录制权限

操作步骤：

1. 打开 系统偏好设置 → 隐私与安全性 → 隐私。
2. 选择左侧边栏的 屏幕录制。
3. 点击 锁图标，输入密码解锁。
4. 点击 + 号，添加你的终端应用或 MCP 客户端。
5. 重启应用。

支持的应用：

• Terminal.app：/Applications/Utilities/Terminal.app
• Claude Desktop：/Applications/Claude.app
• VS Code：/Applications/Visual Studio Code.app

2. 辅助功能权限（可选）

若要对窗口进行操作，需要授予此权限：

1. 打开 系统偏好设置 → 隐私与安全性 → 隐私。
2. 选择左侧边栏的 辅助功能。
3. 添加你的终端或 MCP 客户端应用。

验证 Peekaboo 是否正常运行

# 查看 Peekaboo 帮助信息
./peekaboo --help

# 检查服务器状态
./peekaboo list server_status --json-output

# 进行屏幕截图测试（需要权限）
./peekaboo image --mode screen --format png

# 启动 Peekaboo 服务
peekaboo-mcp

预期输出：

{
  "success": true,
  "data": {
    "swift_cli_available": true,
    "permissions": {
      "screen_recording": true
    },
    "system_info": {
      "macos_version": "14.0"
    }
  }
}

💻 使用示例

🖼️ image - 屏幕捕获

捕获整个主屏幕并保存

{
  "tool_name": "image",
  "arguments": {
    "mode": "screen",
    "path": "~/Desktop/myscreen.png",
    "format": "png"
  }
}

Peekaboo 会返回保存文件的详细信息。

捕获 Finder 活动窗口并返回 Base64 数据

{
  "tool_name": "image",
  "arguments": {
    "app": "Finder",
    "mode": "window",
    "return_data": true,
    "format": "jpg"
  }
}

Peekaboo 会直接返回图像数据，方便 AI 分析，同时也会告知图像的保存位置（如果指定了路径）。

捕获 Google Chrome 的所有窗口并将其置于前台

{
  "tool_name": "image",
  "arguments": {
    "app": "Google Chrome",
    "mode": "multi",
    "capture_focus": "foreground",
    "path": "~/Desktop/ChromeWindows/" 
  }
}

👁️ list - 信息列表

列出所有运行的应用程序

{
  "tool_name": "list",
  "arguments": {
    "item_type": "running_applications"
  }
}

Peekaboo 会列出所有活动的应用程序及其 PID 等信息。

列出 Preview 应用的所有窗口，包括窗口边界和 ID

{
  "tool_name": "list",
  "arguments": {
    "item_type": "application_windows",
    "app": "Preview",
    "include_window_details": ["bounds", "ids"]
  }
}

获取服务器当前状态

{
  "tool_name": "list",
  "arguments": {
    "item_type": "server_status"
  }
}

🔮 analyze - 图像分析

使用自动配置的 AI 提供商分析图像

{
  "tool_name": "analyze",
  "arguments": {
    "image_path": "~/Desktop/myscreen.png",
    "question": "图像左上角的主要颜色是什么？"
  }
}

Peekaboo 会调用 AI 进行分析，并返回分析结果。

强制使用 Ollama 特定模型进行分析

{
  "tool_name": "analyze",
  "arguments": {
    "image_path": "~/Desktop/some_diagram.jpg",
    "question": "解释这个图表。",
    "provider_config": {
      "type": "ollama",
      "model": "llava:13b-v1.6"
    }
  }
}

📚 详细文档

配置参数说明

环境变量配置

通过环境变量对 Peekaboo 进行高级配置：

{
  "PEEKABOO_AI_PROVIDERS": "ollama/llava:latest,openai/gpt-4o",
  "PEEKABOO_LOG_LEVEL": "debug",
  "PEEKABOO_LOG_FILE": "~/Library/Logs/peekaboo-mcp-debug.log",
  "PEEKABOO_DEFAULT_SAVE_PATH": "~/Pictures/PeekabooCaptures",
  "PEEKABOO_CONSOLE_LOGGING": "true",
  "PEEKABOO_CLI_PATH": "/opt/custom/peekaboo"
}

可用环境变量说明

AI 提供商配置详解

PEEKABOO_AI_PROVIDERS 环境变量是配置 Peekaboo 分析功能的关键，它决定了 analyze 工具和 image 工具（当提供 question 参数时）使用的 AI 提供商和模型。格式为逗号分隔的 provider_name/model_identifier 字符串，例如： PEEKABOO_AI_PROVIDERS="ollama/llava:latest,openai/gpt-4o,anthropic/claude-3-haiku-20240307"

• provider_name：目前支持 ollama（本地 Ollama 实例）和 openai，计划支持 anthropic。
• model_identifier：指定提供商使用的具体模型，如 llava:latest、gpt-4o。

analyze 工具和 image 工具（当提供 question 参数时）会根据该配置尝试使用 AI 提供商。如果 provider_config 参数设置为 "auto"（analyze 工具默认，image 工具可选），Peekaboo 会按顺序尝试 PEEKABOO_AI_PROVIDERS 中的提供商，检查所需的 API 密钥（如 OPENAI_API_KEY）或服务可用性（如 Ollama 是否在 http://localhost:11434 或 PEEKABOO_OLLAMA_BASE_URL 指定的地址运行）。

你可以通过 analyze 或 image 工具的 provider_config 参数覆盖模型选择或指定特定的提供商。系统会验证其是否可用，如 API 密钥是否存在或服务是否运行。

其他安装方式

从源码安装

# 克隆仓库
git clone https://github.com/steipete/peekaboo.git
cd peekaboo

# 安装依赖
npm install

# 编译 TypeScript 代码
npm run build

# 编译 Swift CLI
cd peekaboo-cli
swift build -c release

# 复制可执行文件
cp .build/release/peekaboo ../peekaboo

# 返回项目根目录
cd ..

# 可选：全局安装
npm link

然后将 Peekaboo 配置到 Claude Desktop 或其他 MCP 客户端：

使用全局安装的配置示例：

{
  "mcpServers": {
    "peekaboo_local": {
      "command": "peekaboo-mcp",
      "args": [],
      "env": {
        "PEEKABOO_LOG_LEVEL": "debug",
        "PEEKABOO_CONSOLE_LOGGING": "true"
      }
    }
  }
}

使用 node 直接运行的配置示例：

{
  "mcpServers": {
    "peekaboo_local_node": {
      "command": "node",
      "args": [
        "/Users/steipete/Projects/Peekaboo/dist/index.js"
      ],
      "env": {
        "PEEKABOO_LOG_LEVEL": "debug",
        "PEEKABOO_CONSOLE_LOGGING": "true"
      }
    }
  }
}

请将 /Users/steipete/Projects/Peekaboo/dist/index.js 替换为你本地项目的实际路径。同时，使用本地配置时，请确保在 MCP 客户端的服务器列表中使用唯一的键（如 "peekaboo_local" 或 "peekaboo_local_node"），以避免与 npx 安装的 "peekaboo" 服务器冲突。

使用 AppleScript 进行简单截图

# 直接运行 AppleScript
osascript peekaboo.scpt

此方法仅提供简单的截图功能，不支持 MCP 集成和 AI 分析。

其他 MCP 客户端的手动配置

{
  "server": {
    "command": "node",
    "args": ["/path/to/peekaboo/dist/index.js"],
    "env": {
      "PEEKABOO_AI_PROVIDERS": "ollama/llava,openai/gpt-4o"
    }
  }
}

🔧 技术细节

架构设计

Peekaboo/
├── src/                      # Node.js MCP Server (TypeScript)
│   ├── index.ts             # 主 MCP 服务器入口
│   ├── tools/               # 工具实现
│   │   ├── image.ts         # 屏幕捕获工具
│   │   ├── analyze.ts       # AI 分析工具  
│   │   └── list.ts          # 应用/窗口列表工具
│   ├── utils/               # 工具模块
│   │   ├── peekaboo-cli.ts   # Swift CLI 集成
│   │   ├── ai-providers.ts  # AI 提供商管理
│   │   └── server-status.ts # 服务器状态工具
│   └── types/               # 共享类型定义
├── peekaboo-cli/            # 原生 Swift CLI
│   └── Sources/peekaboo/    # Swift 源代码
│       ├── main.swift       # CLI 入口
│       ├── ImageCommand.swift    # 图像捕获实现
│       ├── ListCommand.swift     # 应用列表实现
│       ├── Models.swift          # 数据结构
│       ├── ApplicationFinder.swift   # 应用发现逻辑
│       ├── WindowManager.swift      # 窗口管理
│       ├── PermissionsChecker.swift # macOS 权限检查
│       └── JSONOutput.swift        # JSON 响应格式化
├── package.json             # Node.js 依赖
├── tsconfig.json           # TypeScript 配置
└── README.md               # 本文件

JSON 输出格式

Swift CLI 在使用 --json-output 参数时会输出结构化的 JSON 数据：

{
  "success": true,
  "data": {
    "applications": [
      {
        "app_name": "Safari",
        "bundle_id": "com.apple.Safari", 
        "pid": 1234,
        "is_active": true,
        "window_count": 2
      }
    ]
  },
  "debug_logs": ["Found 50 applications"]
}

协议转换与集成

Node.js 服务器负责在 MCP 的 JSON-RPC 协议和 Swift CLI 的 JSON 输出之间进行转换，提供以下功能：

• Schema 验证：使用 Zod 进行输入输出验证。
• 错误处理：使用 MCP 标准错误码处理错误。
• 日志记录：使用 Pino 记录日志。
• 类型安全：整个 TypeScript 代码库保证类型安全。

权限管理

Peekaboo 严格遵守 macOS 安全机制：

• 权限检查：在进行屏幕捕获操作前检查屏幕录制权限。
• 优雅降级：权限缺失时，功能会优雅降级。
• 错误提示：提供清晰的错误信息，引导用户授予所需权限。

📄 许可证

本项目采用 MIT 许可证，详细信息请参考 LICENSE 文件。

🧛 加入我们

如果你想为 Peekaboo 贡献代码，可以按照以下步骤操作：

1. Fork 本仓库。
2. 创建新的功能分支 (git checkout -b feature/amazing-feature)。
3. 提交你的更改 (git commit -m 'Add amazing feature')。
4. 将分支推送到远程仓库 (git push origin feature/amazing-feature)。
5. 提交 Pull Request。

📜 可用工具（通过 MCP 服务器）

Peekaboo 作为 MCP 服务器运行时，提供以下工具：

• image：捕获 macOS 屏幕内容。

  • 支持捕获整个屏幕、特定应用窗口或应用的所有窗口。
  • 支持多种格式和捕获模式（前台/后台）。
  • 新增功能：可选地提供 question 和 provider_config 参数，对捕获的图像进行即时分析，并返回分析结果和图像详细信息。如果提供了问题，图像文件将是临时的，分析完成后会删除，除非指定了 path 参数。提问时，不会返回图像数据（Base64）。
  • 完整的输入输出 Schema 请参考 docs/spec.md。

• analyze：使用配置好的 AI 模型分析现有图像文件。

  • 需要提供图像路径和问题。
  • 使用 PEEKABOO_AI_PROVIDERS 和 provider_config 配置的 AI 提供商。
  • 完整的输入输出 Schema 请参考 docs/spec.md。

• list：列出系统信息，如运行的应用程序、特定应用的窗口或服务器状态。

  • 完整的输入输出 Schema 请参考 docs/spec.md。

🎃 Peekaboo 随时等待你的指令！它就像一座桥梁，连接 macOS 的隐藏 API 和 Node.js 的强大功能，让你能够轻松捕获屏幕内容并深入分析。祝你使用愉快！👻