pilotfish MCP

An MCP server that gives your AI agent a real Chrome browser on your own computer. Your agent's own model reads each page and picks each step; pilotfish carries the step out, checks it and tells the agent what changed.

For anyone using Claude Code, Codex CLI, Cursor, Claude Desktop, VS Code or another MCP client. Free and MIT licensed: no account, no API key, no pilotfish servers. It needs Node.js 22 or newer and Chrome, Edge or Chromium.

claude mcp add pilotfish -- npx -y @gaiventures/pilotfish-mcp

Setup for other clients is below. To have whole tasks done for you in pilotfish's cloud browser instead, signed in with your saved logins, see "Local or managed?" below.

Why pilotfish

• It clicks what it means to. Tools act on refs from the page (browser_click {ref: "e12"}). If the element is covered, gone or off screen, the click is refused instead of landing on the wrong thing, and every action reports what changed.
• It reads pages cheaply. The agent sees a compact outline of the visible screen. After the first look it gets only the lines that changed, and browser_query pulls out just the values it needs.
• You stay in charge. Sign-ins, one-time codes and CAPTCHAs are handed to you in the browser window. Payments, orders, messages and deletions wait for your yes.
• Your passwords stay out of the model. Secrets you configure are typed as {{name}} placeholders and masked in every result.
• It runs locally. A fresh browser on your machine and your own internet connection, closed when your agent disconnects. Cookie banners are declined and ads and trackers blocked before the agent sees the page.

Local or managed?

This package is the local version. pilotfish managed (@gaiventures/pilotfish-mcp-managed) is a paid service: pilotfish runs the whole task in its cloud browser and hands your agent the result.

Use local when you are at your desk and want your agent to drive. Use managed when you want a task done, need to stay signed in to sites between runs, or keep running into bot checks. Managed needs a pilotfish account (sign up with Google); its package page has every client's setup, the tools and the prices.

Tasks that name no site. Your agent searches the web first (with its own search tool) to pick the site, or answers from the search when that is enough. It opens a site with browser_navigate when the task needs one: a price for your dates, a form, an account. With this package the search is your agent's, not pilotfish's.

Requirements

• Node.js 22 or newer
• Google Chrome, Microsoft Edge or Chromium. Set PILOTFISH_CHROME to choose one.

Setup

Claude Code

claude mcp add pilotfish -- npx -y @gaiventures/pilotfish-mcp

On native Windows (not WSL), use claude mcp add pilotfish -- cmd /c npx -y @gaiventures/pilotfish-mcp. Settings go before the -- as -e NAME=value, for example -e PILOTFISH_HEADLESS=1.

Codex CLI

In ~/.codex/config.toml:

[mcp_servers.pilotfish]
command = "npx"
args = ["-y", "@gaiventures/pilotfish-mcp"]
# browser_resume waits up to 300 s for you; Codex stops a call after 60 s by default.
tool_timeout_sec = 330
# Optional:
# env = { PILOTFISH_HEADLESS = "1", PILOTFISH_ALLOWED_HOSTS = "example.com,*.example.com" }

Cursor, Claude Desktop, Windsurf and others

In Cursor's ~/.cursor/mcp.json (or .cursor/mcp.json in a project), Claude Desktop's claude_desktop_config.json, or your client's equivalent:

{
  "mcpServers": {
    "pilotfish": {
      "command": "npx",
      "args": ["-y", "@gaiventures/pilotfish-mcp"]
    }
  }
}

Settings go in an env object next to args. npx -y runs the newest release; to stay on one, put its number after the name (@gaiventures/pilotfish-mcp@<version>). npx -y @gaiventures/pilotfish-mcp --version prints the version you have.

The browser opens in its own window, where you sign in or solve a CAPTCHA when a page needs a person. PILOTFISH_HEADLESS=1 hides it; on a Linux machine without a display it is hidden already.

Over HTTP

One browser shared by every client that connects, on 127.0.0.1:

npx -y @gaiventures/pilotfish-mcp --http --port 8931
claude mcp add --transport http pilotfish http://127.0.0.1:8931/mcp

Clients that take a URL use "url": "http://127.0.0.1:8931/mcp". The server only answers requests addressed to localhost. Set PILOTFISH_MCP_TOKEN to require Authorization: Bearer <token>; it is required to serve on any other address.

Tools

How it behaves

Each screen once. Your agent pays for every token it reads, and new tokens cost far more than ones it has already seen. So when the agent acts on a page it saw in one of its last 8 results, it gets only the lines that changed, each under its unchanged parent line marked ~ , with removed elements listed by ref. Refs stay the same between snapshots, so lines it was not sent again still work. If more than half the screen changed it gets the whole screen, and browser_snapshot always returns everything.

Pages that need a person. After each action the page is checked. A sign-in it has no credentials for, a one-time code or two-factor prompt, a device approval, a sign-in link, a passkey, 3-D Secure or a CAPTCHA adds a NEEDS A PERSON note to the result. You handle it in the browser window and the agent calls browser_resume. pilotfish never tries to get past these pages itself: no guessed passwords or codes, no CAPTCHA solving. A client that supports elicitation asks you directly. A bot check that clears on its own is waited out first, for up to 12 seconds. BLOCKED: means the site refused this browser, and STOP: marks a site that must not be automated.

Confirmations. Actions that look irreversible (pay, place an order, send, delete) need your yes. A client with elicitation asks you; any other client gets the action refused, with the reason.

Settings

All optional.

Example with a secret:

"env": {
  "PILOTFISH_SECRETS": "{\"shop_password\": {\"value\": \"...\", \"allowedHosts\": [\"shop.example.com\"]}}"
}

Privacy

pilotfish connects only to the sites your agent opens, plus the public ad-block lists (EasyList, EasyPrivacy and uBlock Origin's filters), downloaded about once a week and cached in ~/.pilotfish/adblock. No telemetry, no pilotfish servers, no model providers.

Troubleshooting

• "No Chromium executable found": install Google Chrome, or set PILOTFISH_CHROME to the path of Chrome, Edge or Chromium.
• The server does not start on Windows: start npx through cmd /c (see Claude Code above), and check node --version is 22 or newer.
• A call times out while you sign in: raise your client's tool timeout above 300 seconds (Codex: tool_timeout_sec), since browser_resume waits up to 300 s for you.
• A site keeps blocking the browser: this package uses your own IP and a plain Chrome, and never solves CAPTCHAs. Clear the check in the browser window yourself, or use pilotfish managed.

More from pilotfish

• pilotfish managed: whole tasks in the cloud, signed in as you.
• The pilotfish app: run tasks from the web, save logins, watch live, see replays.

License

MIT