High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
MCP Server
PinchTab includes a native Model Context Protocol (MCP) server that lets AI agents control the browser through MCP over stdio.
[!WARNING] The MCP server is part of PinchTab's privileged control plane. It is intended for trusted operators and trusted agent systems only. Do not expose it to untrusted users, untrusted client systems, or the public internet. If you are unsure how to secure a non-local deployment, review Security and use the private security contact path in
SECURITY.mdbefore exposing the service.
[!CAUTION] By default, PinchTab's IDPI posture is meant to keep MCP browsing local-only until you deliberately widen it. Expanding MCP use to non-local or non-trusted domains is a security-reducing choice.
When MCP tools read page content from wider domains, treat
pinchtab_snapshotandpinchtab_get_textoutput as untrusted data, not instructions. Hostile pages can contain prompt-injection content, poisoned text, or other material that should never be treated as operator guidance. Review Security before relaxing domain restrictions.
Quick Start
- Start PinchTab in server or bridge mode:
pinchtab server # or pinchtab bridge - Start the MCP server in another terminal or from your MCP client config:
pinchtab mcp
The MCP server communicates over stdio using JSON-RPC, which is the standard MCP transport.
Client Configuration
Claude Desktop
{
"mcpServers": {
"pinchtab": {
"command": "pinchtab",
"args": ["mcp"]
}
}
}
VS Code / GitHub Copilot
{
"servers": {
"pinchtab": {
"type": "stdio",
"command": "pinchtab",
"args": ["mcp"]
}
}
}
Cursor
{
"mcpServers": {
"pinchtab": {
"command": "pinchtab",
"args": ["mcp"]
}
}
}
Grok Build
After PinchTab is listed in the official xAI marketplace, install the plugin with:
grok plugin install pinchtab --trust
Until then, or to install from the PinchTab repository marketplace:
grok plugin marketplace add pinchtab/pinchtab
grok plugin install pinchtab --trust
You can also install the plugin directory directly from GitHub:
grok plugin install pinchtab/pinchtab#plugins/grok --trust
From the root of a local checkout, use grok plugin install ./plugins/grok --trust. --trust is required before MCP starts. The plugin does not install the pinchtab binary; install PinchTab separately and run pinchtab server or the local daemon.
To wire MCP yourself instead of the plugin, add to ~/.grok/config.toml:
[mcp_servers.pinchtab]
command = "pinchtab"
args = ["mcp"]
For first use, verification, domain authorization, and troubleshooting, see the Grok plugin install and usage guide.
Environment
| Variable | Description |
|---|---|
PINCHTAB_TOKEN |
Auth token for secured servers |
For remote servers, use the root --server flag with that host's credential — a non-loopback host requires PINCHTAB_TOKEN (or PINCHTAB_SESSION), since the CLI refuses to send the local config's server.token off the machine:
PINCHTAB_TOKEN=<that-host-token> pinchtab --server http://remote:9867 mcp
Available Tools
PinchTab currently exposes 47 tools:
- Navigation: 9
- Interaction: 8
- Keyboard: 1
- Content: 4
- Recording: 1
- Site: 1
- Tab management: 6
- Human handoff: 3
- Wait utilities: 1
- Network: 6
- Diagnostics: 6
- Dialog: 1
Navigation
pinchtab_navigatepinchtab_back— go back one history entry; returns the tab ID and the URL landed onpinchtab_forward— go forward one history entry; returns the tab ID and the URL landed onpinchtab_reload— reload the current page; returns the tab ID and the URL landed onpinchtab_snapshotpinchtab_framepinchtab_screenshotpinchtab_capture— paired screenshot + snapshot from one DOM epochpinchtab_get_text— extract page text;modeselectsreadability(default),raw, ormarkdown(preserves links and tables, best for article-shaped pages).modesupersedes the legacy booleanraw. Example:pinchtab_get_text {"mode":"markdown"}
Interaction
pinchtab_clickpinchtab_typepinchtab_hoverpinchtab_focuspinchtab_selectpinchtab_scrollpinchtab_scroll_into_viewpinchtab_fill
Keyboard
pinchtab_key—actionispress,down,up,typeorinsert
Content
pinchtab_evalpinchtab_pdfpinchtab_findpinchtab_extract— typed values against a JSONschema(tabId,scope,maxItemsoptional); every field carries a ref for the action tools and a confidence. Prefer it over snapshot-then-parse for structured values, and pin alowfield withx-pinchtab-hint. See Extract
Recording
pinchtab_record—actionisstart,stoporstatus
Site
pinchtab_scrape— crawl a site to markdown (HTTP-first, browser-enrich thin/JS pages). Usepreview=truefor a cheap outline, then expand chosen URLs withonly. ItstimeoutSecondsis a crawl budget and the one seconds-unit argument; every wait elsewhere istimeoutMs.
Tab Management
pinchtab_list_tabspinchtab_close_tabpinchtab_healthpinchtab_cookies(requiressecurity.allowCookies)pinchtab_cookies_set(requiressecurity.allowCookies)pinchtab_connect_profile
Human Handoff
pinchtab_handoff— pause a tab (tabIdrequired;reason,timeoutMsoptional) so a human can finish a CAPTCHA, login or consent step; every action tool on that tab is refused withtab_paused_handoffuntil it resumespinchtab_resume— resume the tab (tabIdrequired;statusoptional). Call it only after the user confirms they finishedpinchtab_handoff_status— reportpaused_handoff(withreason,pausedAt,expiresAt) oractive, so an agent can watch atimeoutMsauto-resume without resuming itself
Wait Utilities
pinchtab_wait—forisms,selector,text,url,loadorfunction, andvaluecarries the condition;timeoutMsbounds a browser-backed wait (timeoutis its deprecated alias)
Network
pinchtab_networkpinchtab_network_detailpinchtab_network_clearpinchtab_network_routepinchtab_network_unroutepinchtab_network_rules
Diagnostics
pinchtab_console— read (orclear) the tab's browser console logspinchtab_errors— read (orclear) the tab's uncaught JavaScript exceptions; check this when a snapshot looks healthy but actions do nothingpinchtab_a11y_audit— accessibility audit;engine=axeruns vendored axe-core in the isolated world and returns ref-mapped violations with WCAG tags and help URLspinchtab_memory— JavaScript heap usage and DOM counters for the tab;gc=truecollects garbage first so two reads compare retained memorypinchtab_memory_snapshot— take a V8 heap snapshot to a server-side file and return only its path and a summary (top constructors, duplicate strings); needssecurity.allowMemory. See Memorypinchtab_memory_compare— compare two snapshot ids: per-constructor count and self-size deltas, largest first, plus new duplicate strings;retained=trueadds retained sizes from the head snapshot's dominator tree; needssecurity.allowMemory
Dialog
pinchtab_dialog
Selector Model
For selector-based interaction tools, prefer selector. ref, element and target are still accepted as deprecated aliases on the element-action tools.
Argument Names
Every tool refuses an argument its schema does not declare. The call returns an error naming the unknown key, the nearest declared name when one is close (filter: "interactive" on pinchtab_snapshot points at interactive: true), and the tool's declared arguments; nothing runs. Deprecated spellings stay declared, with a description naming the canonical one: ref/element/target for selector, timeout for timeoutMs on pinchtab_wait, onDialog/promptText for dialogAction/dialogText on pinchtab_click, value for text on pinchtab_type, option for value on pinchtab_select, and text for value on pinchtab_fill.
Common selector forms:
e5#loginxpath://buttontext:Submitfind:login button
Practical Flow
The normal MCP browser loop is:
- Call
pinchtab_navigatewith aurl - Call
pinchtab_snapshotto inspect page structure and collect refs - Call
pinchtab_click,pinchtab_type, or other action tools with structured arguments - Call
pinchtab_waitorpinchtab_networkwhen needed - Call
pinchtab_backto leave a dead end, orpinchtab_reloadto retry the page
pinchtab_back, pinchtab_forward and pinchtab_reload take an optional tabId
and snap, so snap: true returns the page after the navigation in one
round-trip.
pinchtab_snapshot supports MCP-safe output controls:
compact=trueorformat="compact"for the most token-efficient text snapshotformat="text"for the full text snapshotnoAnimations=trueto reduce animation noise before capture
For full parameter details, see MCP Tool Reference.