pinchtab-mcp

npm version npm downloads codecov License: MIT Node.js

Smithery Glama mcp.so

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