pinchtab-mcp

What is this?

PinchTab is a standalone Go binary that gives AI agents full control over a Chrome browser via an HTTP API. It is token-efficient, headless-capable, and supports persistent browser profiles.

pinchtab-mcp is a thin Model Context Protocol (MCP) stdio server that wraps PinchTab's HTTP API — making it available as a standard MCP tool in any compatible AI coding agent or chat client.

AI client (OpenCode / Cursor / Claude Desktop)
        │  MCP stdio (JSON-RPC)
        ▼
  pinchtab-mcp  ──HTTP──▶  PinchTab :9867  ──CDP──▶  Chrome

Why a separate MCP wrapper?

PinchTab exposes a plain HTTP API. MCP clients communicate over stdin/stdout using JSON-RPC. This server bridges the two, adding:

• Single pinchtab tool with a unified action parameter — minimal context bloat

• Typed, validated inputs via Zod

• Auth token forwarding, configurable timeout

• Screenshot responses as MCP image content (base64 JPEG)

Related MCP server: BrowserGenie MCP Server

Prerequisites

Install PinchTab

# macOS / Linux — recommended
curl -fsSL https://pinchtab.com/install.sh | bash

# Docker
docker run -d -p 9867:9867 ghcr.io/pinchtab/pinchtab:latest

Note: npm install -g pinchtab does not reliably install the binary on all platforms. Use the install script or Docker instead.

Full PinchTab docs: pinchtab.com/docs

Setup

1. Clone and build

git clone https://github.com/domci/pinchtab-mcp.git
cd pinchtab-mcp
npm install
npm run build

This compiles src/index.ts to dist/index.js.

2. Start PinchTab

In a separate terminal — PinchTab must be running before the MCP server is used:

# Basic
pinchtab

# With an auth token (recommended)
BRIDGE_TOKEN=my-secret pinchtab

If the MCP tool returns Connection failed, PinchTab is not running. Start it as above and retry.

3. Configure your client

OpenCode

Add to ~/.config/opencode/opencode.json (global) or opencode.json in your project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pinchtab": {
      "type": "local",
      "command": ["node", "/absolute/path/to/pinchtab-mcp/dist/index.js"],
      "enabled": true,
      "environment": {
        "PINCHTAB_URL": "http://localhost:9867",
        "PINCHTAB_TOKEN": "my-secret"   // omit if no auth token
      }
    }
  }
}

Cursor IDE

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "pinchtab": {
      "command": "node",
      "args": ["/absolute/path/to/pinchtab-mcp/dist/index.js"],
      "env": {
        "PINCHTAB_URL": "http://localhost:9867",
        "PINCHTAB_TOKEN": "my-secret"
      },
      "type": "stdio"
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "pinchtab": {
      "command": "node",
      "args": ["/absolute/path/to/pinchtab-mcp/dist/index.js"],
      "env": {
        "PINCHTAB_URL": "http://localhost:9867"
      }
    }
  }
}

Environment variables

Tool reference

A single pinchtab tool is registered. All operations are dispatched via the action parameter.

Actions

All actions accept an optional tabId to target a specific tab.

Token strategy

Example prompts

Navigate to https://news.ycombinator.com and extract the top 10 story titles.
use pinchtab

Go to https://example.com/login, fill in the username and password fields, and submit the form.
use pinchtab

Take a screenshot of the current page.
use pinchtab

Development

# Install dependencies
npm install

# Build (TypeScript → dist/)
npm run build

# Run directly
node dist/index.js

Project structure

pinchtab-mcp/
├── src/
│   └── index.ts       # MCP stdio server — all logic lives here
├── dist/              # Compiled output (git-ignored)
├── package.json
└── tsconfig.json

Troubleshooting

Connection failed: fetch failed. Is PinchTab running at http://localhost:9867? The PinchTab binary is not running. Start it with pinchtab in a separate terminal, then retry.

npm install -g pinchtab installs but pinchtab command is not found The npm package does not install the Go binary on all platforms. Use the install script instead:

curl -fsSL https://pinchtab.com/install.sh | bash

press Enter doesn't submit a form / page doesn't navigate Some sites handle form submission via click events on the submit button rather than keyboard events on the input. Use click on the submit button ref instead of press Enter on the input.

Search input shows "queryEnter" as its value This happens when press appends literally to the field value. Use fill to set the value cleanly, then click the submit button.

Security notes

• BRIDGE_TOKEN / PINCHTAB_TOKEN — always set a token in production environments; rotate it regularly.

• evaluate executes arbitrary JavaScript inside Chrome — restrict access to trusted agents and domains.

• PinchTab should not be exposed to the public internet; keep it on localhost or behind a private network.

License

MIT — see LICENSE.