🚀 Peekaboo MCP:极速截屏,宛如超自然现象
Peekaboo MCP 是一款超自然的 macOS 实用工具,它能像幽灵一样迅速捕捉屏幕快照,并借助超自然的 AI 视觉洞察窗口内容。有了它,你的 AI 助手将拥有真正的视觉能力,轻松应对各种与视觉相关的任务。
🚀 快速开始
召唤 Peekaboo 的仪式要求
- 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"
}
}
}
}
- 重启 Claude Desktop
完成以上步骤,Peekaboo 就会从数字世界中现身,准备好为你的屏幕服务!
✨ 主要特性
为何你的 AI 需要视觉能力
- 🐛 漏洞排查:让 AI 真正看到布局问题,提高排查效率。
- 📸 即时分析:一键截图并提问,实现快速分析。
- 🎨 设计评审:借助视觉证据,让 AI 对 CSS 问题进行评估。
- 📊 数据分析:AI 能够解读图表中的数据。
- 🖼️ UI 测试:确保应用在不同设备上显示正常,避免“在我机器上正常”的问题。
- 📱 多屏幕魔法:随时捕捉任何窗口、任何应用的画面。
- 🤖 自动化魔法:让 AI 看到你所看到的,然后修复问题。
Peekaboo 就像是为你的编码助手配备的超自然隐形眼镜,从此无需再反复解释“提交”按钮的位置!
📦 安装指南
召唤 Ollama - 本地视觉预言家
Ollama 提供了强大的本地 AI 能力,无需将数据上传到云端即可分析截图。以下是召唤 Ollama 的步骤:
📦 安装 Ollama
macOS(通过 Homebrew):
brew install ollama
访问 ollama.ai 并下载 macOS 应用。
启动 Ollama 守护进程:
ollama serve
守护进程默认运行在 http://localhost:11434
。
🎭 下载视觉模型
对于性能强大的机器,推荐使用 LLaVA(大型语言和视觉助手)模型:
ollama pull llava:latest
ollama pull llava:7b-v1.6
ollama pull llava:13b-v1.6
ollama pull llava:34b-v1.6
对于性能较弱的机器,Qwen2-VL 模型在资源需求较低的情况下仍能提供出色的性能:
ollama pull qwen2-vl:7b
模型大小指南:
qwen2-vl:7b
- 约 4GB 下载量,约 6GB RAM 要求(适合轻量级机器)
llava:7b
- 约 4.5GB 下载量,约 8GB RAM 要求
llava:13b
- 约 8GB 下载量,约 16GB RAM 要求
llava:34b
- 约 20GB 下载量,约 40GB RAM 要求
🔮 配置 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 是否正在运行且可访问:
curl http://localhost:11434/api/tags
./peekaboo image --app Finder --path ~/Desktop/finder.png
授予神秘权限
Peekaboo 需要 macOS 的特定权限才能发挥其强大功能:
1. 👁️ 全视之眼权限
执行权限仪式:
- 打开 系统偏好设置 → 安全性与隐私 → 隐私
- 从左侧边栏选择 屏幕录制
- 点击 锁图标 并输入密码
- 点击 + 并添加你的终端应用程序或 MCP 客户端
- 重启应用程序
已知可使用 Peekaboo 的应用程序:
- Terminal.app:
/Applications/Utilities/Terminal.app
- Claude Desktop:
/Applications/Claude.app
- VS Code:
/Applications/Visual Studio Code.app
2. 🪄 窗口低语者权限(可选)
若要对窗口发送命令并使其响应:
- 打开 系统偏好设置 → 安全性与隐私 → 隐私
- 从左侧边栏选择 辅助功能
- 添加你的终端/MCP 客户端应用程序
验证 Peekaboo 是否成功启动
./peekaboo --help
./peekaboo list server_status --json-output
./peekaboo image --mode screen --format png
peekaboo-mcp
预期输出:
{
"success": true,
"data": {
"swift_cli_available": true,
"permissions": {
"screen_recording": true
},
"system_info": {
"macos_version": "14.0"
}
}
}
💻 使用示例
基础用法
1. 🖼️ 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 会直接返回图像数据,同时提供图像可能保存位置的信息。
捕捉“Google Chrome”的所有窗口并将其置于前台:
{
"tool_name": "image",
"arguments": {
"app": "Google Chrome",
"mode": "multi",
"capture_focus": "foreground",
"path": "~/Desktop/ChromeWindows/"
}
}
2. 👁️ 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"
}
}
3. 🔮 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"
}
📚 详细文档
替代召唤仪式
🧪 从源代码构建
如果你想从源代码构建 Peekaboo,可以按照以下步骤操作:
git clone https://github.com/steipete/peekaboo.git
cd peekaboo
npm install
npm run build
cd peekaboo-cli
swift build -c release
cp .build/release/peekaboo ../peekaboo
cd ..
npm link
然后将 Peekaboo 绑定到 Claude Desktop(或其他 MCP 客户端):
示例 MCP 客户端配置(使用本地构建):
如果你运行了 npm link
并且 peekaboo-mcp
已在你的 PATH 中:
{
"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
替换为你克隆项目中 dist/index.js
的实际绝对路径。同时,使用这些本地配置时,请确保在 MCP 客户端的服务器列表中使用不同的键(如 "peekaboo_local" 或 "peekaboo_local_node"),以避免与基于 npx 的 "peekaboo" 服务器配置冲突。
🍎 古老的 AppleScript 仪式
如果你想使用简单的方式进行截图,可以运行古老的 AppleScript:
osascript peekaboo.scpt
这种方式仅提供简单的截图功能,不包含 MCP 集成或 AI 分析功能。
其他 MCP 客户端的手动配置
对于除 Claude Desktop 之外的 MCP 客户端,可以使用以下配置:
{
"server": {
"command": "node",
"args": ["/path/to/peekaboo/dist/index.js"],
"env": {
"PEEKABOO_AI_PROVIDERS": "ollama/llava,openai/gpt-4o"
}
}
}
可用工具(通过 MCP 服务器)
Peekaboo 在作为 MCP 服务器运行时,通过以下工具提供其功能:
🔧 技术细节
超自然能力
🖼️ 空灵视觉捕捉
- 多屏幕捕捉:分别捕捉每个屏幕的画面。
- 精准定位:通过模糊匹配功能,准确捕捉指定应用或窗口的画面。
- 多种格式支持:支持 PNG、JPEG、WebP、HEIF 等多种图像格式。
- 智能命名:根据时间和描述自动生成文件名。
- 权限检测:自动验证所需的权限。
👻 精灵管理
- 全面的应用列表:提供所有正在运行的应用程序的详细信息。
- 窗口信息查询:可以查询每个应用程序的窗口信息和元数据。
- 模糊匹配:通过部分名称、应用 ID 或进程号查找应用程序。
- 状态监控:实时监控应用程序的活动状态和窗口数量。
🧿 神谕集成
- 多神谕支持:目前支持 Ollama(通过直接 API 调用)和 OpenAI(通过其官方 Node.js SDK),未来计划支持 Anthropic 等其他神谕。
- 图像分析:可以使用自然语言对捕捉的图像进行查询和分析。
- 可配置性:通过环境变量选择不同的 AI 提供商。
架构概述
Peekaboo/
├── src/ # Node.js MCP Server (TypeScript)
│ ├── index.ts # Main MCP server entry point
│ ├── tools/ # Individual tool implementations
│ │ ├── image.ts # Screen capture tool
│ │ ├── analyze.ts # AI analysis tool
│ │ └── list.ts # Application/window listing
│ ├── utils/ # Utility modules
│ │ ├── peekaboo-cli.ts # Swift CLI integration
│ │ ├── ai-providers.ts # AI provider management
│ │ └── server-status.ts # Server status utilities
│ └── types/ # Shared type definitions
├── peekaboo-cli/ # Native Swift CLI
│ └── Sources/peekaboo/ # Swift source files
│ ├── main.swift # CLI entry point
│ ├── ImageCommand.swift # Image capture implementation
│ ├── ListCommand.swift # Application listing
│ ├── Models.swift # Data structures
│ ├── ApplicationFinder.swift # App discovery logic
│ ├── WindowManager.swift # Window management
│ ├── PermissionsChecker.swift # macOS permissions
│ └── JSONOutput.swift # JSON response formatting
├── package.json # Node.js dependencies
├── tsconfig.json # TypeScript configuration
└── README.md # This file
技术实现细节
📜 结构化输出
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 输出之间进行转换,提供以下功能:
- 模式验证:使用 Zod 进行输入验证。
- 错误处理:使用适当的 MCP 错误代码处理错误。
- 日志记录:使用 Pino 日志记录器进行日志记录。
- 类型安全:整个 TypeScript 代码库具有类型安全性。
🚪 权限管理
Peekaboo 尊重 macOS 的安全机制,在进行截图操作前会检查屏幕录制权限,并在权限缺失时提供清晰的错误信息,引导用户授予所需权限。
📄 许可证
本项目采用 MIT 许可证,详细信息请参阅 LICENSE 文件。
🧛 加入社区
如果你想为 Peekaboo 项目做出贡献,可以按照以下步骤操作:
- Fork 仓库
- 创建功能分支 (
git checkout -b feature/amazing-feature
)
- 提交更改 (
git commit -m 'Add amazing feature'
)
- 推送至分支 (
git push origin feature/amazing-feature
)
- 打开 Pull Request
🎃 Peekaboo 等待你的命令!这个神秘的工具将 macOS 的隐藏 API 与 Node.js 的强大功能相结合,让你拥有捕捉屏幕和解读其中奥秘的能力。祝你使用愉快!👻