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
