pilotfish
Official# pilotfish: open MCP and SDKs
[](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp)
[](https://www.npmjs.com/package/@gaiventures/pilotfish)
[](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp-managed)
[](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.gAI-ventures/pilotfish)
[](LICENSE)
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](https://webmachinelearning.github.io/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](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp))
- **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](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.gAI-ventures/pilotfish))
- **Issues:** <https://github.com/gAI-ventures/pilotfish-ai/issues>
## Install
[](https://cursor.com/install-mcp?name=pilotfish&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBnYWl2ZW50dXJlcy9waWxvdGZpc2gtbWNwIl19)
[](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522pilotfish%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540gaiventures%252Fpilotfish-mcp%2522%255D%257D)
[](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522pilotfish%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540gaiventures%252Fpilotfish-mcp%2522%255D%257D)
Each button opens the app with the server filled in, for you to review and add.
**Claude Code**, in a terminal:
```sh
claude mcp add pilotfish -- npx -y @gaiventures/pilotfish-mcp
```
or as a plugin, from this repository's plugin marketplace, inside Claude Code:
```text
/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.
```json
{
"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>.
## SDKs
TypeScript:
```ts
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:
```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.
```sh
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](CONTRIBUTING.md). Security issues: [SECURITY.md](SECURITY.md).
## License
MIT, see [LICENSE](LICENSE).
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.