pinchtab-mcp

MCP server for PinchTab — control Chrome (or any Chromium browser) via accessibility tree snapshots through the Model Context Protocol.

PinchTab is included as a dependency and starts automatically — no manual setup required.

Quick Start

npx pinchtab-mcp

Or install globally:

npm install -g pinchtab-mcp
pinchtab-mcp

Client Setup

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

With a custom browser (see Configuration):

{
  "mcpServers": {
    "pinchtab": {
      "command": "npx",
      "args": ["-y", "pinchtab-mcp"],
      "env": {
        "CHROME_BINARY": "/Applications/Yandex.app/Contents/MacOS/Yandex",
        "BRIDGE_HEADLESS": "false"
      }
    }
  }
}

Cursor / VS Code — add to .cursor/mcp.json or .vscode/mcp.json:

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

Claude Code:

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

Configuration

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

Binary lookup order: PINCHTAB_BIN → node_modules/.bin/pinchtab → system PATH.

PinchTab Configuration

PinchTab itself is configured via env variables or a config file (~/.config/pinchtab/config.json):

Variable	Default	Description
CHROME_BINARY	(bundled Chromium)	Path to browser binary — use this for Yandex Browser, Brave, Edge, etc.
CDP_URL	(none)	Connect to an already-running browser's DevTools (e.g. http://localhost:9222)
BRIDGE_HEADLESS	true	Set to false to see the browser window
BRIDGE_PORT	9867	PinchTab HTTP API port
BRIDGE_TOKEN	(none)	Protect the API with an auth token
BRIDGE_PROFILE	~/.config/pinchtab/chrome-profile	Browser profile directory (cookies, sessions)
BRIDGE_MAX_TABS	20	Max open tabs
BRIDGE_BLOCK_ADS	false	Block ads
BRIDGE_BLOCK_IMAGES	false	Block image loading (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	(none)	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

# Microsoft Edge
CHROME_BINARY="/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" npx pinchtab-mcp

# Visible browser (non-headless) for debugging
BRIDGE_HEADLESS=false npx pinchtab-mcp

# Custom window size (default: random common resolution for stealth)
CHROME_FLAGS="--window-size=1920,1080" npx pinchtab-mcp

# Connect to an existing browser session (keeps your tabs, cookies, logins)
CDP_URL="http://localhost:9222" npx pinchtab-mcp

Documentation

For tools reference, project structure, agent workflow, and code style see PROJECT_INDEX.md.

Contributing

See CONTRIBUTING.md.

License

MIT