pilotfish
OfficialDrive a real local Chrome browser from an MCP agent to browse, read, and interact with web pages.
Open http(s) URLs and receive evidence plus a snapshot of visible elements with refs.
Read pages via compact snapshots, page text, screenshots, and read-only JavaScript queries for specific values.
Find elements by visible words or labels, including outside the viewport.
Click, type, select options, press keys, and scroll with safety checks and change evidence.
Run multiple actions in one call, stopping on failure or navigation.
Wait for loading or text changes, list/switch browser tabs, and close/restart the browser.
Pause for a person to handle sign-in, 2FA, CAPTCHA, or device approval, then resume.
Provides browser automation using a real Google Chrome instance on the user's computer. The MCP server can launch Chrome, drive pages over the Chrome DevTools Protocol, interact with frames and page elements, capture page snapshots and evidence, and handle cookie banners and ads.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pilotfish open my Gmail and draft a reply to the newest unread email"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pilotfish MCP
Give any MCP agent (Claude Code, Codex CLI, Cursor, ...) a real Chrome on your own computer. Free, no account, no
API key: your agent's own model reads each page and decides every step through the browser_* tools, and this
server makes no model calls.
Install:
npx -y @gaiventures/pilotfish-mcp(npm)Docs: https://pilotfish.gai.ventures/docs/open (setup per client, tools, settings)
MCP Registry:
io.github.gAI-ventures/pilotfish(listing)Issues: https://github.com/gAI-ventures/pilotfish-mcp/issues
Install
Each button opens the app with the server filled in, for you to review and add.
Claude Code, in a terminal:
claude mcp add pilotfish -- npx -y @gaiventures/pilotfish-mcpor as a plugin, from this repository's plugin marketplace, inside Claude Code:
/plugin marketplace add gAI-ventures/pilotfish-mcp
/plugin install pilotfish-browser@pilotfishAny other MCP client (Codex CLI, Cline, Windsurf, ...): add this to its MCP settings.
{
"mcpServers": {
"pilotfish": { "command": "npx", "args": ["-y", "@gaiventures/pilotfish-mcp"] }
}
}Node 22 or later and Google Chrome (or Chromium) on the same computer. Setup per client: https://pilotfish.gai.ventures/docs/open.
Related MCP server: huashu-chrome
What is here
Folder | What |
| The local MCP server (stdio, or Streamable HTTP with |
| A stdio relay to pilotfish's hosted MCP, for clients that only speak stdio. Published as |
| A thin, typed Chrome DevTools Protocol client. |
| Launching Chrome and driving pages over raw CDP: frames, hit-tested input, settling after an action. |
| Structure-first page snapshots, element handles, and the evidence diff after each action. |
| Cookie banners and ads handled deterministically, with maintained rule sets. |
| The executor every tool runs through: policy before page-affecting actions, secrets typed as |
| The server as a plugin for Claude Code ( |
| The server entry, read by directories that index this repository; opening the repository in Claude Code offers to start it too. |
The managed MCP
The hosted service (whole tasks run in pilotfish's cloud browser, saved logins, saved and scheduled tasks, replays)
is separate and is not in this repository. Connect to it at https://pilotfish-be.gai.ventures/mcp, or over stdio
with the relay in packages/mcp-managed: npx -y @gaiventures/pilotfish-mcp-managed. See
https://pilotfish.gai.ventures/docs.
Build and test
Node 22 or later.
npm ci
npm run build
npm test # unit tests
PILOTFISH_E2E=1 npx vitest run packages/mcp --testTimeout 120000 # the MCP against a real Chrome
npm run package # the npm packages, in packages/*/npm-packageThe browser tests use Google Chrome when it is installed; set PILOTFISH_CHROME to a Chromium binary to use another.
Contributing
This repository is a mirror: it is published from pilotfish's own repository, and every sync replaces its whole tree. Pull requests are welcome; see CONTRIBUTING.md. Security issues: SECURITY.md.
License
MIT, see LICENSE.
Available Tools
16 toolsbrowser_actionsSeveral actions in one callADestructiveInspect
Several steps in order in one call, e.g. fill a form's fields and submit it; each gets the same checks as its own tool. Stops at the first that fails, or after one that moves the page to another address (later refs would belong to the old page). Returns a line per step and the evidence and visible screen after the last one run.
Inputs: actions (required).
browser_clickClickADestructiveInspect
Click an element by ref. Refuses with a reason (obscured, stale, not visible) instead of clicking the wrong thing. Returns evidence of what changed.
Inputs: ref (required).
browser_closeClose the browserADestructiveInspect
Only to start over: closes the browser, and the next call starts a fresh one (cookies and logins are gone). It closes by itself when the client disconnects.
Inputs: no named parameters.
browser_findFind elementsARead-onlyInspect
Refs of elements anywhere on the page, outside the visible screen too, by the words they show or are labelled with, best match first. Separate several targets by commas.
Inputs: query (required).
browser_get_textPage textARead-onlyInspect
Readable text of the page (PDFs too), secrets masked, without refs. To read a few values or a list, browser_query is far smaller.
Inputs: selector, max_chars.
browser_pressPress a keyADestructiveInspect
Press a key or shortcut on whatever has focus (no ref; browser_click a field first). E.g. Escape closes a dialog, ArrowDown then Enter picks a suggestion; Enter may submit a form; reload keys are refused. For text, browser_type. Returns what changed.
Inputs: key (required).
browser_queryRead values with JavaScriptARead-onlyInspect
Read just the values you need (prices, counts, titles, a results list) with a read-only JavaScript expression returning JSON (at most 4000 characters): the cheapest way to read, far smaller than browser_get_text or a snapshot. It runs in a world of its own where clicks, typing, submits and network writes are refused.
Inputs: expression (required), schema.
browser_resumeContinue after the personARead-onlyInspect
When a result says NEEDS A PERSON (a sign-in, a one-time code or 2FA, a device approval, a CAPTCHA), tell the user in your reply what the page needs and that the pilotfish browser window is open on it; when they have done it there (or right after asking), call this and carry on: it waits until the page has moved on, then returns it. BLOCKED and STOP mean the site cannot be continued that way.
Inputs: timeout_s.
browser_screenshotScreenshotARead-onlyInspect
JPEG of the current viewport. Prefer browser_snapshot (cheaper, has refs); use this when layout or images matter.
Inputs: no named parameters.
browser_scrollScrollAInspect
Scroll the page about one screen; returns the screen now in view, with refs. To reach a named element, browser_find; for text, browser_get_text.
Inputs: direction (required).
browser_selectSelect optionsAIdempotentInspect
Choose options of a native by label or value, replacing the current selection (unlisted options are unselected). Custom dropdown: browser_click it, then the option. Returns the values selected and what changed.
Inputs: ref (required), values (required).
browser_snapshotRead the pageARead-onlyInspect
The current page as a compact tree of headings, text and elements with refs (e12) to act on: three screens around the viewport, or everything with whole_page. Refs stay valid while their element is on the page.
Inputs: whole_page.
browser_tabsTabsAInspect
List the open tabs (the current one is marked). switch_to makes another tab current and returns its snapshot.
Inputs: switch_to.
browser_typeTypeADestructiveInspect
Replace the text of an input, textarea or editable element by ref (never appends). In an autocomplete box the result shows its suggestions: browser_click one. For a , browser_select. Returns what changed.
Inputs: ref (required), text (required), submit.
browser_waitWaitARead-onlyInspect
Wait 0.5-10 seconds (until/gone: up to that, returning once the text appears or goes), then return what changed. Only for a page still loading or saying it is working: actions already wait for the requests they start.
Inputs: seconds (required), gone, until.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools have sharply distinct purposes, and the descriptions actively route the agent (snapshot vs screenshot vs get_text vs query, click vs type vs select vs press). The reading cluster (snapshot, find, get_text, query) overlaps somewhat in that all reveal page content, but each is clearly scoped by cost and by whether refs are returned. No two tools appear to do the same thing.
Every name carries the same browser_ prefix and is lowercase snake_case, which makes the set predictable. A few names are bare nouns (browser_snapshot, browser_screenshot, browser_tabs, browser_actions) rather than verb_noun like browser_get_text, so it is not a single uniform pattern. Still highly consistent overall.
Sixteen tools is on the heavy side but sits just inside a reasonable range for a full browser-automation surface. Each tool maps to a real capability (navigate, read, click, type, select, press, scroll, wait, tabs, close, batch, human handoff) rather than being filler. The count is defensible, though a few read variants could conceivably be merged.
The core browser lifecycle and interaction loop is fully covered, including batch actions and a NEEDS A PERSON handoff via browser_resume, which is a thoughtful completeness feature. Gaps are minor: no explicit hover or drag, no back/forward history navigation, and no file-upload tool. Agents can usually work around these (e.g. keyboard shortcuts), but not always.
Maintenance
Related MCP Connectors
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Browz hosted MCP (free public beta): let an AI app drive your own Browz browser profiles from anywhere. Connect https://mcp.gobrowz.com/mcp and sign in with your Browz account (OAuth) or an agent token. Each call is relayed to the Browz app on your computer, which must be online with Remote control on and have a hardware security chip (Mac Secure Enclave or TPM 2.0). 17 tools: profiles, tabs, navigate, snapshot, act, wait, screenshot. Cookies, downloads and stored sign-ins stay on your computer.
Let your AI agent operate any website through a real, logged-in browser session.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI coding assistants to control and inspect a live Chrome browser through Chrome DevTools. Provides browser automation, performance analysis, debugging capabilities, and network request monitoring.2,562,190 npm57,558Apache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables any MCP-compatible AI agent to drive your own Chrome browser with your existing login state, filling forms, clicking elements, fetching data, and handling captchas without API keys or re-authentication.1,276 npm598MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to see and control the user's real Chrome/Brave/Edge profile over MCP, so they can read pages, click, type, take screenshots, audit layouts, debug CSS, and scrape paginated or infinite-scroll data. Because it drives the normal browser via the DevTools protocol with real input events, it works on modern JavaScript apps and on sites where the user is logged in.17 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables any MCP-capable AI client to drive the user's own Chrome or Edge browser through a set of browse_* tools — navigating, clicking, typing, extracting, and managing tabs with their existing logins on their own machine. Runs locally and self-hosted with a live viewport and pause/approve controls so every verified step stays under user watch.4MIT