Poltertab

PolterTab — Browser Control for Any AI

Let any AI agent use the Chrome you're already logged into. PolterTab is a Chrome extension plus a local MCP (Model Context Protocol) server.

A Chrome extension + Model Context Protocol (MCP) server. The AI acts inside the browser you already use: your real profile, your cookies, your logged-in sessions. Install the extension, point your MCP client at the server, done — it works with Claude Desktop, Cursor, or any MCP-compatible agent.

Why PolterTab

• Your real profile — runs in the Chrome you're already signed into. No fresh headless browser that's logged out of everything.
• No complex setup — add the extension from the Chrome Web Store, add one MCP entry. That's it.
• Any AI tool — any MCP-compatible client can connect.

How It Works

Any MCP Agent (Claude Desktop, Cursor, custom agents)

│ Stdio (MCP Protocol) ▼ Node.js MCP Server (mcp-server/index.js) │ WebSocket (port 7822 by default) ▼ PolterTab Chrome Extension │ Chrome APIs + DOM ▼ Your existing Chrome profile

Several agents can point at the same browser at once — the first server to claim the WebSocket port serves the extension and the rest proxy through it. See Running several agents at once.

What leaves your machine

PolterTab runs entirely on your machine. There is no PolterTab server, account, or telemetry.

• The MCP server is local. It talks to your AI client over stdio, and the WebSocket the extension uses listens only on this machine (127.0.0.1 and ::1, port 7822 by default). The server refuses connections from web pages — browser connections must come from a Chrome extension (chrome-extension://) origin — and only the Chrome Web Store build (trusted automatically) or an extension you have paired can hold that connection, change upload settings, or read the logs. (architecture)
• Page content goes only where your agent sends it. PolterTab returns what it reads or scrapes to your MCP client; your client forwards it to whatever model provider *you* have configured. PolterTab itself transmits page content nowhere.
• File uploads are off until you allow a folder. browser_upload_file refuses every path until you add a folder with poltertab uploads allow , and sensitive locations are always blocked and cannot be allowlisted. Run poltertab uploads to see the current list.
• npm provenance. Releases are published with npm publish --provenance, so npm records a signed, verifiable link from the published tarball back to the GitHub Actions build that produced it.
• One exception — the version check. The running server makes one outbound request, a daily npm version check (registry.npmjs.org); poltertab setup additionally does a one-time Chrome Web Store version lookup (clients2.google.com). Both only compare versions to warn about a server/extension mismatch — no page content or personal data is sent. Turn both off with POLTERTAB_NO_UPDATE_CHECK=1.

From 1.12.0, only the Chrome Web Store extension or one you have paired can control the browser; an unpacked install pairs once with poltertab uploads pair.

To report a vulnerability, see SECURITY.md.

Setup

Requires Node 18 or newer.

1. Run the installer

npm install -g poltertab

poltertab setup

The wizard asks whether to install for all projects or just the current one, then puts three things in place:

• the browser-navigation-strategy skill, so the agent knows how to drive a browser that fights back
• a CLAUDE.md section, so it knows the tools exist
• the MCP server registration, via claude mcp add

It is safe to re-run — each step detects its own prior work, so an upgrade or a second pass will not duplicate anything.

Prefer not to install globally? npx poltertab setup does the same thing.

2. Install the Chrome Extension

[Add to Chrome](https://chromewebstore.google.com/detail/poltertab-browser-control/lcijocampajjmennelacdfehmhndfmbd) from the Chrome Web Store. Chrome keeps a Store extension up to date on its own, so this is the install path for everyone who is not developing the extension itself.

Then restart your AI tool so it picks up the new tools.

Or load it unpacked (developer / offline path)

Use this when you are changing the extension or cannot reach the Web Store. An unpacked extension never updates on its own; you reload it from a newer zip yourself.

1. Download the latest release zip and unzip it into its own folder (e.g. unzip poltertab-extension-vX.zip -d poltertab-extension, or double-click on macOS — which creates a folder automatically)
2. Open Chrome → chrome://extensions/
3. Enable Developer mode (top right toggle)
4. Click Load unpacked and select that folder (the one containing manifest.json)
5. Pair it once so it can control the browser: run poltertab uploads pair and enter the 4-character code the extension shows. (Store installs are trusted automatically and skip this.)

Other MCP clients

The wizard targets Claude Code. Any other MCP client works too — register poltertab as a stdio command:

{

"mcpServers": { "poltertab": { "command": "poltertab" } } }

Using [Cursor](https://cursor.com)? One-click install (adds the stdio entry above):

Running from a clone instead of npm? Point the client at the file directly: {"command": "node", "args": ["/absolute/path/to/poltertab/mcp-server/index.js"]}

Supported MCP Tools

The server exposes 28 tools to the LLM (all prefixed with browser_). Every page-facing tool also takes optional tabId and session to target a specific tab — omit both and PolterTab uses the agent's current tab: the last one it navigated, opened or switched to. The first browser_navigate (and the first browser_navigate of each new session) opens its own tab rather than commandeering the one you are looking at.

Page actions

Reading the page

Every tool here takes output_file, which writes the payload to ~/.poltertab/downloads/ and returns only a summary — row count, field names, fill rates and two sample records. Use it for anything bigger than a glance; the raw payload should never be the default path into a context window.

Extracting records

browser_scrape returns a flat list, which loses track of which value belongs to which record. That is fine for one element and dangerous for ninety: the moment a field is optional, a flat scrape of names against phone numbers shifts every later phone up a row and mis-assigns the rest of the page.

browser_extract takes a record container and resolves each field *inside* it:

{

"record": ".agent-card", "fields": { "name": { "sel": "a.agent-card-name", "get": "text" }, "url": { "sel": "a.agent-card-name", "get": "href" }, "phone": { "sel": "a[href^='tel:']", "get": "href", "strip": "tel:" }, "socials": { "sel": "a.social-button", "get": "href", "many": true } }, "anchor": "url", "output_file": "agents.csv" }

• A missing field yields `null`. It never shifts.
• sel is relative to the record root; omit it (or use ".") for the root itself.
• get is text (default), href, src, or any attribute name.
• anchor names the field a real record always has. Records missing it — the placeholder cards that pad the last page of a listing — are dropped and counted in dropped rather than emitted as rows of nulls.

The result reports what happened, so an empty column cannot pass for an answer:

{ "count": 12, "dropped": 0,

"fill_rates": { "name": 12, "phone": 10, "socials": 0 }, "warnings": ["socials: 0/12 within record scope, but 40 matches page-wide for a.social-button — record boundary likely too narrow"] }

That warning is the loosening probe. Any field that comes back entirely empty is re-checked page-wide, because the container that *looks* like the record often excludes a sibling holding some of the fields — and "0 socials" reads as "these people have no social accounts" rather than "your selector scope is wrong".

`browser_extract_all` takes the same spec plus a url_template containing {page}, and runs the loop itself. It dedups on key and halts on the first of: limit_reached, empty_page, duplicate_page (a page whose records repeat an earlier one — what a site does when it ignores an unrecognised page-size param), fill_rate_deviation (a page whose fill rates collapse against the first page's baseline, which is how a spec learned on page 1 quietly degrades on page 10), or max_pages. It always reports which condition fired and returns everything collected up to that point, so a halt never costs you the run.

.csv and .jsonl output files are written in those formats.

Network capture

For sites whose DOM is obfuscated or virtualized, read the JSON driving the UI instead of scraping elements that may not exist.

| `browser_set_intercept_p