holoscrape-mcp

Give an AI agent your own logged-in browser. This runs locally, does not upload anything, and never sees your passwords — the HoloScrape Chrome extension does the actual reading, in your own signed-in Chrome, and this process is only the bridge that lets an MCP-speaking agent (Claude Code, Claude Desktop, Cursor, Windsurf) ask it to.

Use it

You do not install this — your agent's MCP config runs it on demand:

{
  "mcpServers": {
    "holoscrape": { "command": "npx", "args": ["-y", "holoscrape-mcp@latest"] }
  }
}

Then open the HoloScrape side panel in Chrome once. The extension finds your agent's server on its own — there is no code to copy or type. After the first connection it reconnects by itself whenever the browser and your agent are both running, and Claude Code, Claude Desktop and Cursor can all be connected at the same time.

Cursor: press ⌘⇧P and run Open MCPs — it opens the Customize editor on its MCPs tab (recent versions have no MCP entry in Settings). Click New MCP Server, which opens mcp.json, paste the block above and save. Or edit ~/.cursor/mcp.json (every project) / .cursor/mcp.json (one project) directly. holoscrape should then appear in that list with its tools; if not, run Developer: Reload Window. Cursor starts the server itself, so nothing else needs to be running. @latest matters: without it npx keeps reusing whatever version it cached first.

Unlock the full HoloScrape MCP: the headless companion (one more command, once)

npx -y holoscrape-mcp@latest --install-browser

This downloads Chromium for Testing (about 150 MB) through Playwright. It is the only step that downloads anything, and it is never done silently — you run it. The command checks first: if the browser this version needs is already there it downloads nothing, and after a download it confirms the server can find it. Run it again after updating holoscrape-mcp. npx -y holoscrape-mcp@latest --check-browser only reports (exit 0 = ready), and the server prints the same check when it starts.

What it unlocks: a companion browser the server launches itself, headless, with the same extension loaded and no session in it. Your own Chrome stays the default and the only place a signed-in site is ever read. The companion steps in, on its own, when a lane in your Chrome cannot paint a page: DevTools open on the tab, or a managed Chrome that blocks the debugger (a policy Chrome 155 ships in October 2026). It also steps back out: a page that wants your login is bounced in the companion and re-run in your Chrome. Every reply that switched says so (switched).

Without this step everything still works in your Chrome; a reply that would have switched carries one sentence telling you to run the command above. To turn the companion off for a session, set HOLOSCRAPE_COMPANION=0 in the server's env.

Related MCP server: MCP Browser

What it can do

Once connected, an agent can read whatever list is on a page in this browser — a search results grid, a directory listing, a table — and walk its pages. Any http or https site can be read; a short list of restricted hosts (video and music streaming) stays off limits no matter what. Tools that act — navigate, press, type — are marked as such, so your agent asks you before each one.

On a page with more than one scrollable region — a chat app's sidebar list beside an open conversation, a filter rail beside results — the automatic ranking favours the denser pane, which may not be the one you mean. The fix is two calls: page_study lists every candidate with its selector, and list_extract with that selector pinned reads exactly that pane:

page_study   { tabId: 12 }                                    → lists[1].selector: "aside.rail>div.chats…"
list_extract { tabId: 12, selector: "aside.rail>div.chats…" } → grows and reads the sidebar, not the feed

Why local

The alternative is a hosted relay that sees every page it reads. This process listens only on 127.0.0.1 — never on your network — and refuses any connection from a web page (by the Origin header, which a page cannot fake), so a site you visit cannot pose as the extension. Cookies and auth tokens are never handed to the agent: credential-shaped values come back masked.

Tools

Try it without an agent

node try.mjs tabs
node try.mjs study <tabId>

Drives the same stdio protocol an agent would, useful for checking the whole chain — this script → the server → the WebSocket → the extension → a real tab — works before pointing a real agent at it.

Requirements

• Node.js 18+

• The HoloScrape Chrome extension, installed (open its side panel once)

• Optional, for the headless companion: Chromium for Testing via npx -y holoscrape-mcp@latest --install-browser

License

MIT