eyeshot-mcp

Built by DeepSeek

中文

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

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

Configuration

opencode

Add to ~\.config\opencode\opencode.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