# ScreenshotsMCP

> Give your AI coding assistant eyes and hands for the web. Screenshot any URL, automate browsers, solve CAPTCHAs, create disposable email inboxes, audit performance and SEO — all via MCP tools.

ScreenshotsMCP is a Model Context Protocol (MCP) server with 46+ tools that gives AI coding assistants the ability to see, interact with, and test websites. It works with Claude, Cursor, Windsurf, VS Code, and any MCP-compatible client.

## Agent Skill

Download the complete Agent Skill for all tools: https://screenshotsmcp.com/.skills/screenshotsmcp/SKILL.md

## Quick Start

### Option A: CLI (fastest)

```bash
npx screenshotsmcp login
npx screenshotsmcp install cursor    # or: vscode, windsurf, claude, claude-code
```

### Option B: Manual

1. Get an API key at https://screenshotsmcp.com/dashboard/keys
2. Add to your MCP config:

```json
{
  "mcpServers": {
    "screenshotsmcp": {
      "url": "https://screenshotsmcp-api-production.up.railway.app/mcp/YOUR_API_KEY"
    }
  }
}
```

3. Ask your AI: "Take a screenshot of https://example.com"

## VS Code Extension Preview

A native ScreenshotsMCP VS Code extension is now being developed in the monorepo for a dedicated Activity Bar sidebar, automatic browser OAuth sign-in, API key fallback, native MCP registration, command palette actions, a live activity timeline panel, and browser workflow UX inside the editor.

Current preview commands include `ScreenshotsMCP: Sign In`, `ScreenshotsMCP: Check Status`, `ScreenshotsMCP: Take Screenshot`, `ScreenshotsMCP: Open Timeline`, and `ScreenshotsMCP: Install MCP Server in Workspace`. The sidebar also exposes quick actions and recent activity directly in VS Code, and the extension opens browser OAuth automatically when no credentials are stored.

Until the Marketplace release is ready, the recommended VS Code setup is still:

- `npx screenshotsmcp setup --client vscode`
- or manual `.vscode/mcp.json` configuration

## CLI (for agents and humans)

ScreenshotsMCP has a CLI that exposes all tools as terminal commands. **AI agents can and should use the CLI directly via terminal/run_command** — it's often faster than MCP tool calls and returns structured text output.

Install: `npm install -g screenshotsmcp`
npm: https://www.npmjs.com/package/screenshotsmcp
Or use without installing: `npx screenshotsmcp <command>`

### Auth
```
screenshotsmcp login                    # OAuth (opens browser, saves key)
screenshotsmcp login --key sk_live_...  # Direct API key
screenshotsmcp whoami                   # Check auth status
screenshotsmcp logout                   # Clear credentials
```

### Screenshots
```
screenshotsmcp screenshot <url>                    # 1280×800 viewport
screenshotsmcp screenshot <url> --width 1920 --height 1080 --full-page
screenshotsmcp screenshot <url> --format jpeg --delay 2000
screenshotsmcp responsive <url>                    # Desktop + tablet + mobile
screenshotsmcp mobile <url>                        # iPhone 14 Pro (393×852)
screenshotsmcp tablet <url>                        # iPad (820×1180)
screenshotsmcp dark <url>                          # Dark mode emulated
screenshotsmcp element <url> --selector "#hero"    # CSS element capture
screenshotsmcp diff <urlA> <urlB>                  # Pixel-diff two URLs
screenshotsmcp cross-browser <url>                 # Chromium + Firefox + WebKit
screenshotsmcp batch <url1> <url2> <url3>          # Multiple URLs (max 10)
screenshotsmcp pdf <url>                           # Export as PDF
```

### Browser Sessions
```
screenshotsmcp browse <url>                                    # Start session → sessionId
screenshotsmcp browse:click <sessionId> <selector>             # Click element
screenshotsmcp browse:fill <sessionId> <selector> <value>      # Type into input
screenshotsmcp browse:screenshot <sessionId>                   # Capture current state
screenshotsmcp browse:text <sessionId>                         # Get visible text
screenshotsmcp browse:html <sessionId>                         # Get page HTML
screenshotsmcp browse:scroll <sessionId> --y 500               # Scroll down
screenshotsmcp browse:key <sessionId> Enter                    # Press key
screenshotsmcp browse:goto <sessionId> <newUrl>                # Navigate
screenshotsmcp browse:close <sessionId>                        # End session
```

### Reviews & Audits
```
screenshotsmcp review <url>              # AI UX review
screenshotsmcp seo <url>                 # SEO metadata
screenshotsmcp perf <url>                # Core Web Vitals
screenshotsmcp a11y <url>                # Accessibility tree
screenshotsmcp breakpoints <url>         # Responsive breakpoints
```

### Disposable Email
```
screenshotsmcp inbox:create              # Create inbox → email@agentmail.to
screenshotsmcp inbox:check <inboxId>     # Read messages, extract OTP codes
screenshotsmcp inbox:send <inboxId> --to user@example.com --subject "Test" --text "Hello"
```

### Setup & Install
```
screenshotsmcp setup                     # Interactive: login + choose IDE + auto-configure (recommended)
screenshotsmcp setup --client cursor     # Non-interactive: for AI agents, skips prompt
screenshotsmcp setup --client windsurf
screenshotsmcp setup --client vscode
screenshotsmcp setup --client claude
screenshotsmcp setup --client claude-code
screenshotsmcp install cursor            # Writes ~/.cursor/mcp.json
screenshotsmcp install vscode            # Writes .vscode/mcp.json
screenshotsmcp install windsurf          # Writes ~/.codeium/windsurf/mcp_config.json
screenshotsmcp install claude            # Writes Claude Desktop config
screenshotsmcp install claude-code       # Prints `claude mcp add` command
```

### One-liner Install
```
# macOS/Linux
curl -fsSL https://screenshotsmcp.com/install.sh | bash

# Windows PowerShell
irm https://screenshotsmcp.com/install.ps1 | iex

# Or just use npx (no install needed)
npx screenshotsmcp setup
```

### Agent Tips
- **AI agents: use `npx screenshotsmcp setup --client <ide>` to install non-interactively.**
- **Use CLI when you have terminal access** — structured text output, no JSON-RPC overhead.
- Every screenshot command returns a public CDN URL.
- Browser sessions: start with `browse`, get sessionId, pass to subsequent commands, always `browse:close` when done.
- Credentials stored in `~/.config/screenshotsmcp/config.json`. Once logged in, all commands are authenticated.
- Use `npx screenshotsmcp` if unsure whether it's installed globally.

## Server URL

MCP endpoint: `https://screenshotsmcp-api-production.up.railway.app/mcp/YOUR_API_KEY`
REST API base: `https://screenshotsmcp-api-production.up.railway.app`
Transport: Streamable HTTP

## Authentication

Every request requires an API key. Keys start with `sk_live_`.

- MCP: API key is embedded in the server URL path
- REST API: Pass as `Authorization: Bearer sk_live_...` header

Rate limits by plan:
- Free: 100 screenshots/month
- Starter: 2,000 screenshots/month
- Pro: 10,000 screenshots/month

---

## Tools Reference (46+ tools)

### Screenshot Tools (no session needed)

#### take_screenshot
Capture a screenshot of any URL and return a public image URL.

Parameters:
- url (string, required): The URL to screenshot
- width (number, default: 1280): Viewport width in pixels (320–3840)
- height (number, default: 800): Viewport height in pixels (240–2160)
- fullPage (boolean, default: true): Capture full scrollable page
- maxHeight (number, optional): Cap extremely tall captures
- format (string, default: "png"): png, jpeg, or webp
- delay (number, default: 0): Wait ms after page load (0–10000)

#### screenshot_fullpage
Capture entire scrollable page.
Params: url, width, format, maxHeight

#### screenshot_mobile
iPhone 14 Pro (393×852).
Params: url, fullPage, format

#### screenshot_tablet
iPad (820×1180).
Params: url, fullPage, format

#### screenshot_responsive
Desktop + tablet + mobile in ONE call. Most efficient for responsive checks.
Params: url, fullPage, format

#### screenshot_dark
Dark mode emulated (prefers-color-scheme: dark).
Params: url, width, height, format

#### screenshot_element
Specific element by CSS selector. SPA-friendly with auto-wait.
Params: url, selector, format, delay

#### screenshot_pdf
Export as PDF (A4 with backgrounds).
Params: url

#### screenshot_batch
Capture multiple URLs in one call (max 10).
Params: urls[], width, height, format, fullPage

#### screenshot_cross_browser
Chromium + Firefox + WebKit simultaneously.
Params: url, width, height, fullPage

#### screenshot_diff
Pixel-diff two URLs. Returns diff image + percentage changed + match score.
Params: urlA, urlB, width, height, threshold

#### find_breakpoints
Detect responsive breakpoints (scans 320px–1920px).
Params: url

#### list_recent_screenshots
View recent captures.
Params: limit (1–20)

#### get_screenshot_status
Check if a job is done.
Params: id

---

### Browser Session Tools

Start with `browser_navigate` → get sessionId → pass to all tools → `browser_close` when done.

#### browser_navigate
Open URL, returns screenshot + sessionId.
Params: url, sessionId (optional), width, height

#### browser_click
Click by CSS selector or visible text.
Params: sessionId, selector

#### browser_click_at
Click at x,y coordinates — for CAPTCHAs, canvas, iframes.
Params: sessionId, x, y, clickCount, delay

#### browser_fill
Type into input field (clears first).
Params: sessionId, selector, value

#### browser_hover
Trigger hover states/tooltips/dropdowns.
Params: sessionId, selector

#### browser_select_option
Select from dropdown.
Params: sessionId, selector, value

#### browser_press_key
Keyboard: Enter, Tab, Escape, Control+a, etc.
Params: sessionId, key

#### browser_scroll
Scroll by pixel amount.
Params: sessionId, x, y

#### browser_wait_for
Wait for element to appear.
Params: sessionId, selector, timeout

#### browser_go_back / browser_go_forward
Browser history navigation.
Params: sessionId

#### browser_set_viewport
Resize viewport mid-session (e.g. desktop ↔ mobile).
Params: sessionId, width, height

#### browser_close
Free resources. Always call when done.
Params: sessionId

#### browser_screenshot
Screenshot current page state.
Params: sessionId

#### browser_get_text
All visible text (or specific element).
Params: sessionId, selector (optional)

#### browser_get_html
DOM source.
Params: sessionId, selector (optional), outer

#### browser_get_accessibility_tree
Full a11y tree — best for understanding page structure.
Params: sessionId, interestingOnly, maxDepth

#### accessibility_snapshot
A11y tree for any URL without a session.
Params: url, interestingOnly, maxDepth

#### browser_evaluate
Run JavaScript, return result.
Params: sessionId, script

---

### Performance & SEO

#### browser_perf_metrics
Core Web Vitals: LCP, FCP, CLS, TTFB, DOM size, resource counts.
Good thresholds: TTFB < 800ms, FCP < 1.8s, LCP < 2.5s, CLS < 0.1
Params: sessionId

#### browser_network_requests
Full network waterfall with timing.
Params: sessionId, resourceType, minDuration, limit

#### browser_seo_audit
Meta, OG, Twitter cards, headings, JSON-LD, alt text, structured data.
Params: sessionId

---

### Debugging

#### browser_console_logs
Console errors, warnings, logs, exceptions.
Params: sessionId, level, limit

#### browser_network_errors
Failed requests (4xx, 5xx).
Params: sessionId, limit

#### browser_cookies
Get/set/clear cookies.
Params: sessionId, action, cookies[]

#### browser_storage
Read/write localStorage and sessionStorage.
Params: sessionId, storageType, action, key, value

---

### Smart Login

#### find_login_page
Discover login pages via sitemap.xml + common paths.
Params: url

#### smart_login
Auto-detect form fields, fill credentials, submit, report result.
Params: loginUrl, username, password, usernameSelector, passwordSelector, submitSelector

Returns: screenshot + status (SUCCESS/FAILED/UNCERTAIN) + sessionId.

---

### CAPTCHA Solving

#### solve_captcha
Auto-detect and solve Cloudflare Turnstile, reCAPTCHA v2/v3, hCaptcha using AI (CapSolver).
For Clerk-powered sites, automatically calls sign-up/sign-in API with the solved token.
Params: sessionId, type (auto), sitekey (auto), pageUrl (auto), autoSubmit (default: true)

---

### Disposable Email (AgentMail)

Each user needs their own AgentMail API key (free at https://console.agentmail.to). Configure in Dashboard → Settings.

#### create_test_inbox
Create a disposable email inbox → returns email@agentmail.to.
Params: username (optional), display_name (optional)

#### check_inbox
Read messages, auto-extracts OTP codes and verification links.
Params: inbox_id, limit

#### send_test_email
Send email from an inbox.
Params: inbox_id, to, subject, text

---

### Gmail Verification (OAuth)

#### authorize_email_access
One-time OAuth setup for Gmail.

#### read_verification_email
Read OTP codes from user's Gmail inbox.
Params: sender (optional), subject_keyword (optional), max_age_minutes

---

### AI-Powered Analysis

#### ux_review
AI-powered UX review using vision. Returns actionable feedback across Accessibility, SEO, Performance, Navigation, Content, and Mobile-friendliness.
Params: url, width, height

---

## Common Workflows

### Responsive Testing
→ `screenshot_responsive` for desktop + tablet + mobile in one call

### Full Site Audit
→ `browser_navigate` → `browser_get_accessibility_tree` → `browser_perf_metrics` → `browser_seo_audit` → `browser_console_logs` → `browser_network_errors`

### Sign-Up Testing with Disposable Email
1. `create_test_inbox` → email@agentmail.to
2. `browser_navigate` to sign-up page
3. `browser_fill` email + password
4. `solve_captcha` if CAPTCHA present
5. `browser_click` submit
6. `check_inbox` → extract OTP
7. Enter code → done

### Before/After Comparison
→ `screenshot_diff` with urlA and urlB → pixel diff + match score

### Cross-Browser Testing
→ `screenshot_cross_browser` for Chromium + Firefox + WebKit

---

## REST API

Base URL: https://screenshotsmcp-api-production.up.railway.app

### POST /v1/screenshot
Enqueue a screenshot job.
Headers: Authorization: Bearer sk_live_...
Body: { url, width, height, fullPage, format, delay }
Response: { id, status: "pending" }

### GET /v1/screenshot/:id
Poll for status.
Response: { id, status, url, error, createdAt }

---

## Installation by Client

### Cursor
~/.cursor/mcp.json:
```json
{ "mcpServers": { "screenshotsmcp": { "url": "https://screenshotsmcp-api-production.up.railway.app/mcp/YOUR_API_KEY" } } }
```

### Windsurf
```json
{ "mcpServers": { "screenshotsmcp": { "serverUrl": "https://screenshotsmcp-api-production.up.railway.app/mcp/YOUR_API_KEY" } } }
```

### Claude Desktop / Claude Code
```json
{ "mcpServers": { "screenshotsmcp": { "url": "https://screenshotsmcp-api-production.up.railway.app/mcp/YOUR_API_KEY" } } }
```

### VS Code (Copilot)
.vscode/mcp.json:
```json
{ "mcpServers": { "screenshotsmcp": { "url": "https://screenshotsmcp-api-production.up.railway.app/mcp/YOUR_API_KEY" } } }
```

### Gemini CLI / OpenCode / Roo Code / Other MCP clients
```json
{ "mcpServers": { "screenshotsmcp": { "url": "https://screenshotsmcp-api-production.up.railway.app/mcp/YOUR_API_KEY" } } }
```

---

## Documentation

Full docs: https://screenshotsmcp.com/docs
Agent Skill: https://screenshotsmcp.com/.skills/screenshotsmcp/SKILL.md