Skip to main content
Glama

pilotfish: open MCP and SDKs

npm: @gaiventures/pilotfish-mcp npm: @gaiventures/pilotfish npm: @gaiventures/pilotfish-mcp-managed MCP Registry: io.github.gAI-ventures/pilotfish License: MIT

A real Chrome for AI agents and for your own code, that spends fewer tokens and answers sooner: pages go out as compact outlines with refs, and after the first look only what changed, so an agent pays for each screen once.

  • Open MCP (@gaiventures/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. A page that offers its own tools through WebMCP gets them listed with its snapshot, callable with browser_page_tool.

  • SDKs for TypeScript (@gaiventures/pilotfish on npm) and Python (pilotfish, installed from this repository): drive Chrome on your machine from code with the same tools, or send whole tasks to pilotfish's cloud browser over its REST API (tasks, batches, identities, saved tasks and schedules, webhooks), with the same names in both languages.

  • Install the MCP: npx -y @gaiventures/pilotfish-mcp (npm)

  • Install an SDK: npm install @gaiventures/pilotfish · pip install "pilotfish @ git+https://github.com/gAI-ventures/pilotfish-ai#subdirectory=sdks/python"

  • Docs: https://pilotfish.gai.ventures/docs/open (the MCP), https://pilotfish.gai.ventures/docs/sdk (the SDKs), https://pilotfish.gai.ventures/docs/api (the REST API)

  • MCP Registry: io.github.gAI-ventures/pilotfish (listing)

  • Issues: https://github.com/gAI-ventures/pilotfish-ai/issues

Install

Install in Cursor Install in VS Code Install in VS Code Insiders

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-mcp

or as a plugin, from this repository's plugin marketplace, inside Claude Code:

/plugin marketplace add gAI-ventures/pilotfish-ai
/plugin install pilotfish-browser@pilotfish

Any 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

SDKs

TypeScript:

import { LocalBrowser, Pilotfish } from "@gaiventures/pilotfish";

// Chrome on your machine, through this repository's MCP: no key, no model calls.
const browser = await LocalBrowser.start();
await browser.navigate("https://news.ycombinator.com");
console.log((await browser.query("document.title")).value);
await browser.close();

// A whole task in pilotfish's cloud browser (an API key from Org settings → API keys).
const pf = new Pilotfish({ apiKey: process.env.PILOTFISH_API_KEY });
const task = await pf.tasks.run("Top story on Hacker News right now, with its points");
console.log(task.result?.result);

Python:

from pilotfish import LocalBrowser, Pilotfish

with LocalBrowser.start() as browser:
    browser.navigate("https://news.ycombinator.com")
    print(browser.query("document.title").value)

pf = Pilotfish()  # reads PILOTFISH_API_KEY
task = pf.tasks.run("Top story on Hacker News right now, with its points")
print(task["result"]["result"])

Docs: https://pilotfish.gai.ventures/docs/sdk. Sources: packages/sdk (TypeScript) and sdks/python (Python).

What is here

Folder

What

packages/mcp

The local MCP server (stdio, or Streamable HTTP with --http): the tools, settings and the hand-off to a person. Published as @gaiventures/pilotfish-mcp.

packages/mcp-managed

A stdio relay to pilotfish's hosted MCP, for clients that only speak stdio. Published as @gaiventures/pilotfish-mcp-managed.

packages/sdk

The TypeScript SDK: Pilotfish (the hosted REST API) and LocalBrowser (this repository's MCP over stdio). Published as @gaiventures/pilotfish.

sdks/python

The Python SDK, the same clients with the same names, sync and async (pilotfish).

packages/cdp

A thin, typed Chrome DevTools Protocol client.

packages/browser

Launching Chrome and driving pages over raw CDP: frames, hit-tested input, settling after an action.

packages/perception

Structure-first page snapshots, element handles, and the evidence diff after each action.

packages/interrupts

Cookie banners and ads handled deterministically, with maintained rule sets.

packages/agent

The executor every tool runs through: policy before page-affecting actions, secrets typed as {{name}} and never shown to the model, evidence after.

plugins/pilotfish-browser

The server as a plugin for Claude Code (.claude-plugin/plugin.json, .mcp.json) and Cursor (.cursor-plugin/plugin.json, mcp.json), listed by the marketplace files .claude-plugin/marketplace.json and .cursor-plugin/marketplace.json.

.mcp.json

The server entry, read by directories that index this repository; opening the repository in Claude Code offers to start it too.

Local or managed?

This repository holds the local version, free and MIT licensed, and the SDKs for both. pilotfish managed is a paid service: pilotfish runs the whole task in its cloud browser and hands your agent the result.

Local (this repository)

Managed

Who does the work

Your agent's model, one step at a time.

pilotfish runs the whole task and returns the result (the browser_task tool).

Browser and IP

A fresh Chrome on your computer, on your own IP, closed when your agent disconnects.

pilotfish's cloud browser, which keeps running when your computer is off.

Sites that block bots

You clear each check yourself.

Handled by the managed service. See the managed docs and pricing page for what is included.

Sign-ins

You sign in each time and nothing is kept.

Saved logins in an encrypted vault, several accounts per site, authenticator-app codes and codes sent to your email or phone.

Watching and cost

The browser window.

Live view, replays, per-task cost and monthly spending limits.

Price

Free.

Pay as you go from $5 of credit. See the pricing page for usage charges.

Connect to managed at https://pilotfish-be.gai.ventures/mcp (sign in with your pilotfish account or use an organization API key), or over stdio with the relay: npx -y @gaiventures/pilotfish-mcp-managed. Docs: https://pilotfish.gai.ventures/docs. Pricing: https://pilotfish.gai.ventures/pricing.

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
PILOTFISH_E2E=1 npx vitest run packages/sdk --testTimeout 120000 # the TypeScript SDK's local client against a real Chrome
npm run package                                                  # the npm packages, in packages/*/npm-package
cd sdks/python && pip install -e ".[test]" && pytest              # the Python SDK (PILOTFISH_E2E=1 for its local client)

The 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 tools
browser_actionsSeveral actions in one callA
Destructive
Inspect

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_clickClickA
Destructive
Inspect

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 browserA
Destructive
Inspect

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 elementsA
Read-only
Inspect

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 textA
Read-only
Inspect

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_navigateOpen a URLA
Destructive
Inspect

Open an http(s) URL in the current tab. Returns evidence and a snapshot of the visible screen (elements carry refs like e12), with counts of what is above and below. Words like cheapest, latest, highest-rated or most mean the site's own sort or tab for that order (a list's default order is usually something else, e.g. 'Best' or 'Featured'): apply it, then read the top. Over several sites, finish one and note the values the next needs before opening it. A task that names no site: search the web first with your own search tool to pick the site, or answer from the search when that is enough; open a site when the task needs one (a price for dates, a form, an account).

Inputs: url (required), snapshot.

browser_pressPress a keyA
Destructive
Inspect

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 JavaScriptA
Read-only
Inspect

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 personA
Read-only
Inspect

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_screenshotScreenshotA
Read-only
Inspect

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 optionsA
Idempotent
Inspect

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 pageA
Read-only
Inspect

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_typeTypeA
Destructive
Inspect

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_waitWaitA
Read-only
Inspect

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

    A3.9/5.0

    Scored across 16 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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,494,666 npm
      58,318
      Apache 2.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      598
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      4
      MIT