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