# eyeshot-mcp

> Built by DeepSeek

[中文](README_zh.md)

**No telemetry, no external calls, no data exfiltration.** Screenshots never leave your machine unless you explicitly send them to the vision API endpoint you configured.

Eyeshot (Screenshot + Vision) — two MCP tools that give your AI the ability to **see**, forming an automated **capture → analyze** pipeline on Windows.

**If your AI already has vision (GPT-4V, Claude, etc.), you only need the screenshot MCP.** The vision MCP is for AIs without built-in vision support.

## Compatibility

Works with any MCP-compatible client: **opencode**, **Claude Desktop**, **Cursor**, **VS Code** (via extensions), or any other MCP host. These are standard MCP tools — not tied to any specific platform.

## Use Cases

- Automated UI testing — After writing frontend code, let AI launch the browser, screenshot, and verify the page
- OCR text recognition — Capture a window or full screen, read text via vision model
- App UI verification — Launch a desktop app, screenshot, and check if UI renders correctly
- AI-assisted debugging — Program crashes? Take a screenshot and let AI look at it

## Installation

### Option 1: Let AI install it (Recommended)

Send this prompt to your AI assistant, it will handle everything:

> "Clone https://github.com/yourname/eyeshot-mcp to my machine, install its dependencies, then configure it as an MCP server in my opencode config file."

### Option 2: Manual install

```bash
git clone https://github.com/yourname/eyeshot-mcp.git
pip install -r requirements.txt
```

## Configuration

### opencode

Add to `~\.config\opencode\opencode.jsonc`:

```jsonc
{
  "mcp": {
    "screenshot": {
      "type": "local",
      "command": ["python", "C:\\path\\to\\eyeshot-mcp\\screenshot_mcp.py"],
      "enabled": true
    },
    "vision": {
      "type": "local",
      "command": ["python", "C:\\path\\to\\eyeshot-mcp\\vision_mcp.py"],
      "enabled": true
    }
  }
}
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `VISION_API_KEY` | (required) | Vision API key |
| `VISION_API_URL` | `https://api.openai.com/v1/chat/completions` | Any OpenAI-compatible endpoint. Example: OpenRouter `https://openrouter.ai/api/v1/chat/completions` |
| `VISION_MODEL` | `qwen/qwen2.5-vl-32b-instruct` | Any VL model |
| `VISION_MAX_WIDTH` | `2048` | Max image width sent to API (0 = no resize) |
| `VISION_MAX_TOKENS` | `512` | Max tokens in API response |
| `SCREENSHOT_BROWSER_CLASSES` | (optional) | Comma-separated extra browser window classes |

## Tool Reference

### `screenshot_capture_to_file`

Capture an existing window or full screen, save to `screenshot.png`, return path.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `window_title` | str | `""` | Window title, empty = full screen |
| `resize_width` | int | `0` | Screenshot resize width, 0 = auto based on display resolution |

**Auto-resolution logic:**
- 4K (3840) → resize to 1920
- 1440p (2560) → resize to 1280
- 1080p (1920) → resize to 960
- Below 1920 → no resize, keep original

### `screenshot_test_window`

Launch program → Wait → Capture → Close (fully automatic).

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `command` | str | required | Launch command, browsers must include `--new-window` |
| `wait_seconds` | int | required | Wait seconds after launch |
| `maximized` | bool | required | Whether to maximize the window |
| `window_title` | str | `""` | Which window to capture; empty = full screen, no close |
| `resize_width` | int | `0` | Same as capture_to_file |

**Browser tab protection:** When a browser is detected without `--new-window`, closing is skipped to protect other tabs. With `--new-window`, the exclusive window is closed normally.

### `vision_analyze_image`

Analyze an image with a vision model, return text result.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_path` | str | required | Image path, e.g. `screenshot.png` |
| `prompt` | str | `"描述这张图片的内容"` | Your question, supports any language |

## Browser Support

| Window Class | Browser |
|-------------|---------|
| `Chrome_WidgetWin_1` | Chrome, Edge (Chromium), Brave, Opera, Vivaldi |
| `MozillaWindowClass` | Firefox |
| `MSEdgeWindowClass` | Edge (UWP / legacy) |
| `ApplicationFrameWindow` | UWP apps & WebView |

Add custom classes: `SCREENSHOT_BROWSER_CLASSES=MyClass1,MyClass2`

## FAQ

**Q: Screenshot text is blurry?**
A: Increase `resize_width` (e.g. `4096`) to keep original resolution.

**Q: Don't know the window title?**
A: Use `tasklist` to list running processes, or capture full screen and let the vision model identify it.

**Q: Why didn't the browser window close?**
A: Closing is skipped without `--new-window` to protect other tabs. Add `--new-window` to your launch command.

**Q: Can I use a different vision model?**
A: Yes. Set `VISION_API_URL` and `VISION_MODEL` env vars. Compatible with any OpenAI-compatible API.

MIT