pinchtab-mcp

MCP server for browser automation — control Chrome or any Chromium browser via accessibility tree snapshots.

$ npx pinchtab-mcp

Why pinchtab-mcp

🌳

Accessibility Tree

Interact via semantic element refs (e0, e1, …) instead of fragile CSS selectors or pixel coordinates.

🤖

Human-Like Input

Real mouse events and character-by-character typing by default. Works with autocomplete, keystroke listeners, SPAs.

🔌

Zero Config

PinchTab is bundled as a dependency. Auto-starts on first call, stops on exit. Just npx pinchtab-mcp.

🌐

Any Chromium Browser

Chrome, Brave, Edge, Yandex Browser, Arc — set CHROME_BINARY or connect to an existing session via CDP_URL.

📸

Screenshots + Snapshots

Visual screenshots for discovery, compact accessibility snapshots for fast interaction. Diff mode for multi-step flows.

⚡

19 Tools

Navigate, click, type, hover, focus, select, scroll, press keys, wait for selectors, screenshot, eval JS, export PDF, extract text.

Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pinchtab": {
      "command": "npx",
      "args": ["-y", "pinchtab-mcp"]
    }
  }
}

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "servers": {
    "pinchtab": {
      "command": "npx",
      "args": ["-y", "pinchtab-mcp"]
    }
  }
}

$ claude mcp add pinchtab -- npx -y pinchtab-mcp

Agent Workflow

pinchtab_navigate — go to URL (use waitMs to get snapshot in one call)

pinchtab_snapshot — get element refs (e0, e1, …); use filter='interactive' for fewer tokens

pinchtab_click / pinchtab_type — interact by ref (use waitMs for post-action snapshot)

pinchtab_wait_for_selector — wait for dynamic content instead of fixed delays

pinchtab_snapshot — verify result

Available Tools

Tool	Description
pinchtab_list_instances	List all open browser instances
pinchtab_navigate	Navigate to a URL — new tab support, waitMs for auto-snapshot
pinchtab_snapshot	Get accessibility tree with element refs. Supports filter, compact format, diff mode
pinchtab_screenshot	Take a page screenshot (base64 JPEG)
pinchtab_click	Click element by ref — real mouse events, waitMs for auto-snapshot
pinchtab_type	Type text into input — human-like keystrokes, clearFirst for React/Vue/Angular
pinchtab_press	Press keyboard key — optionally on a specific element
pinchtab_hover	Hover over element — reveal tooltips, dropdowns
pinchtab_focus	Focus element — trigger autocomplete, focus-dependent UI
pinchtab_select	Select option in a dropdown by value or visible text
pinchtab_scroll	Scroll page or element in any direction
pinchtab_wait	Wait N seconds (1-30, default 3)
pinchtab_wait_for_selector	Wait for CSS selector to appear — polls every 500ms, up to 15s
pinchtab_get_text	Get readable page text (~800 tokens)
pinchtab_eval	Execute JavaScript in page context
pinchtab_pdf	Export current page as PDF
pinchtab_close_tab	Close current or specific tab by ID
pinchtab_cookies	Get all cookies for the current page
pinchtab_health	Check if PinchTab server is running

Configuration

MCP Server

Variable	Default	Description
PINCHTAB_URL	http://127.0.0.1:9867	PinchTab API endpoint
PINCHTAB_TOKEN		Auth token (must match BRIDGE_TOKEN)
PINCHTAB_BIN	(auto)	Explicit path to PinchTab binary

PinchTab

Variable	Default	Description
CHROME_BINARY	(bundled)	Path to browser binary — Yandex, Brave, Edge, etc.
CDP_URL		Connect to a running browser (e.g. http://localhost:9222)
BRIDGE_HEADLESS	true	Set false to see the browser window
BRIDGE_PORT	9867	HTTP API port
BRIDGE_TOKEN		Auth token
BRIDGE_PROFILE	~/.config/pinchtab/chrome-profile	Browser profile directory
BRIDGE_MAX_TABS	20	Maximum open tabs
BRIDGE_BLOCK_ADS	false	Block ads
BRIDGE_BLOCK_IMAGES	false	Block images (faster scraping)
BRIDGE_BLOCK_MEDIA	false	Block video/audio
BRIDGE_NO_ANIMATIONS	false	Disable CSS animations
BRIDGE_STEALTH	light	Anti-detection level
BRIDGE_TIMEZONE	(system)	Override timezone
BRIDGE_USER_AGENT	(auto)	Override User-Agent
CHROME_FLAGS		Extra flags passed to the browser

Custom Browser Examples

# Yandex Browser
CHROME_BINARY="/Applications/Yandex.app/Contents/MacOS/Yandex" npx pinchtab-mcp

# Brave
CHROME_BINARY="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" npx pinchtab-mcp

# Connect to an existing browser (keeps your tabs, cookies, logins)
/Applications/Yandex.app/Contents/MacOS/Yandex --remote-debugging-port=9222
CDP_URL="http://localhost:9222" npx pinchtab-mcp

# Visible browser for debugging
BRIDGE_HEADLESS=false npx pinchtab-mcp