agent-rules/global-rules/mcp-peekaboo-setup.mdc at main · fdiaz/agent-rules · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
---
description: Automated setup for Peekaboo vision-enabled MCP server
globs: ""
alwaysApply: false
---

# MCP Peekaboo Setup

This rule sets up the Peekaboo MCP server, which provides screenshot capture and AI-powered vision analysis capabilities.

## Overview

Peekaboo is a Model Context Protocol server that enables Claude to:
- Take screenshots of your screen
- Analyze images using AI vision models
- Support both OpenAI and Ollama providers

## Prerequisites

- macOS 14.0+ (Sonoma or later)
- Node.js 20.0+
- OpenAI API key (stored in `~/.zshrc`)
- Optional: Ollama with vision models installed

## Configuration

Add this to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/peekaboo-mcp"
      ],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "openai/gpt-4o,ollama/llava:latest",
        "OPENAI_API_KEY": "<READ_FROM_ZSHRC>",
        "PEEKABOO_LOG_LEVEL": "info",
        "PEEKABOO_DEFAULT_SAVE_PATH": "~/Desktop"
      }
    }
  }
}
```

## Security Setup

To securely extract the OpenAI API key from `~/.zshrc`:

```bash
# Extract API key from .zshrc
export OPENAI_API_KEY=$(grep "export OPENAI_API_KEY=" ~/.zshrc | cut -d'"' -f2)

# Update Claude config with the actual key
jq --arg key "$OPENAI_API_KEY" \
  '.mcpServers.peekaboo.env.OPENAI_API_KEY = $key' \
  ~/Library/Application\ Support/Claude/claude_desktop_config.json > tmp.json && \
  mv tmp.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

## Available Tools

Once configured, you'll have access to:

1. **peekaboo_capture_screenshot**
   - Takes a screenshot of the entire screen or a specific display
   - Saves to the default path or specified location

2. **peekaboo_analyze_screenshot**
   - Captures and analyzes a screenshot with AI
   - Uses the configured AI providers for vision analysis

## Usage Examples

### Basic Screenshot
```
Take a screenshot of my screen
```

### Screenshot with Analysis
```
Take a screenshot and tell me what application is currently in focus
```

### Multi-monitor Support
```
Take a screenshot of display 2
```

## Troubleshooting

1. **Permission Issues**
   - Grant screen recording permission to Terminal/Claude
   - System Preferences → Privacy & Security → Screen Recording

2. **API Key Issues**
   - Verify `OPENAI_API_KEY` is set in `~/.zshrc`
   - Check the key is valid and has sufficient credits

3. **Ollama Connection**
   - Ensure Ollama is running: `ollama serve`
   - Verify vision model is installed: `ollama pull llava:latest`

## Provider Configuration

### OpenAI Only
```json
"PEEKABOO_AI_PROVIDERS": "openai/gpt-4o"
```

### Ollama Only
```json
"PEEKABOO_AI_PROVIDERS": "ollama/llava:latest"
```

### Multiple Providers (Fallback)
```json
"PEEKABOO_AI_PROVIDERS": "openai/gpt-4o,ollama/llava:latest"
```

## Log Levels

- `error`: Only errors
- `warn`: Errors and warnings
- `info`: General information (default)
- `debug`: Detailed debugging information

## Related Resources

- [Peekaboo MCP Repository](https://github.com/steipete/peekaboo-mcp)
- [Model Context Protocol Docs](https://modelcontextprotocol.io)