# @gaiventures/pilotfish-mcp 中文文档

规范地址：https://npmcn.com/package/%40gaiventures/pilotfish-mcp/

版本：0\.1\.50
npm 元数据更新时间：2026-11-15T13:02:10.798Z
中文译文更新时间：2026-11-15T21:12:28.135Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gaiventures/pilotfish-mcp
原文对照：https://npmcn.com/package/%40gaiventures/pilotfish-mcp/?lang=original
项目主页：https://pilotfish.gai.ventures/
源码仓库：https://github.com/gAI-ventures/pilotfish

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：474 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：9 个
- 首次发布：2026-11-05T11:39:08.034Z
- 最新版本发布：2026-11-15T13:02:10.601Z
- 近 30 天下载量：10337（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

给任何MCP特工一个真正的Chrome在你自己的电脑上。 免费,没有账户,没有API密钥. mcprush.com-ba6a69f5121bd8a0089bb26a (英语)

## 安装

```sh
npm install @gaiventures/pilotfish-mcp
```

也可以使用：`pnpm add @gaiventures/pilotfish-mcp`、`yarn add @gaiventures/pilotfish-mcp`、`bun add @gaiventures/pilotfish-mcp`

## README

# 试验鱼 MCP

[![npm](https://img.shields.io/npm/v/@gaiventures/pilotfish-mcp)](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/license/mit)

一个MCP服务器,在自己的计算机上给您的AI代理一个真正的Chrome浏览器. 你的经纪人自己的模特都读了 页面并选择每个步骤; 领航鱼带出该步骤,检查并告诉代理人什么变化.

对于使用克洛德代码, Codex CLI, Cursor, Claude D桌面, VS代码或其他代码的人来说 [MCP 磁共振](https://modelcontextprotocol.io/) 客户端。 自由与麻省理工获得许可:没有账户,没有API密钥,没有飞行员鱼服务器. 它需要Node.js 22或更新的Chrome,Edge或Chrome.

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

其他客户端的设置如下. 要完成全部任务 在飞行员的云浏览器,签到 使用您保存的登录符, 请见下文“ 本地或管理” .

[![pilotfish (local) MCP server](https://mcprush.com/badge/pilotfish-local-mcp/card.svg)](https://mcprush.com/to/pilotfish-local-mcp?ref=badge)

## 为什么是领航鱼

-   **它点击它的意思.** 工具从页面对参考文件进行操作(`browser_click {ref: "e12"}`) (中文(简体) ). 如果该元素 被覆盖,去或关闭屏幕, 点击被拒绝 而不是降落在错误的东西上 报告什么改变了.
-   **它廉价地阅读页面.** 代理人看到可见屏幕的紧凑轮廓. 先看完再说 只得到改变的行,和 `browser_query` 拔出它所需要的价值.
-   **你负责.** 签名,一次性代码和CAPTCHA在浏览器窗口中交给您. 付款, 命令、信件和删除等.
-   **你的密码不在模型之外.** 您配置的秘密类型为 `{{name}}` 占位符和蒙面符 在每一个结果.
-   **它在当地运行.** 新的浏览器在您的机器和您的互联网连接上, 当您的代理商关闭时关闭 断开 Cookie的横幅被拒绝,广告和追踪器在代理商看到页面前被屏蔽.

## 本地还是管理?

这个包是本地版本. **管理试验鱼** (单位:千美元)[`@gaiventures/pilotfish-mcp-managed`](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp-managed)是一个 付费服务:领航鱼在其云浏览器中运行整个任务,并将结果交给代理商.

|  | **当地** (本套装) | **管理** |
| --- | --- | --- |
| 是谁干的 | 你经纪人的模特,一步一步 | 领航鱼执行整个任务,返回结果 |
| 你的代理证物 | 每一页 | 每个任务一个或两个电话 |
| 浏览器 | 在你的电脑,你的IP | 飞行员的云浏览器,即使你的电脑关闭 |
| 签名 | 您每次签名; 无保留 | 保存了登录和会话(一个站点的几个账户),两要素代码,电话登录代码 |
| 您产品用户的任务 | 没有 | 身份:每个用户的登录、会话、IP和设备分开,每个用户的费用 |
| 块块的站点 | 你每张支票都清空了 | 住宅IP 隐形浏览和CAPTCHA 解析,以您为最后手段 |
| 观察和历史 | 浏览器窗口 | 现场观看、控制、重播、每任务成本 |
| 价格 | 免费 | 随你便,从5元的信贷中支付 |

当您在您的办公桌并想要您的代理驾驶时使用本地端 。 需要完成任务时使用管理 留在运行之间的地点, 或继续运行到机器人检查。 管理需要一个领航鱼账户 (单位:千美元)[与 Google 签约](https://pilotfish.gai.ventures/signup)页:1 [软件包页面](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp-managed) 每个客户的设置 工具和价格.

**无站点名称的任务 .** 您的代理先搜索网页( 使用自己的搜索工具) 来选择网站, 或回答 从搜索中找到足够。 它打开一个网站与 `browser_navigate` 当任务需要时: 你的约会 表格 账户 有了这个包裹, 搜索是你的代理, 不是飞行员的.

## 所需资源

-   22号节点或更新
-   Google Chrome, 微软边缘或Chrome. 设定 `PILOTFISH_CHROME` 来选择一个.

## 设置

### 克劳德代码

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

在本地窗口( 不是 WSL) 上, 使用 `claude mcp add pilotfish -- cmd /c npx -y @gaiventures/pilotfish-mcp`。 。 。 . 设置在 `--` 作为 `-e NAME=value`,例如 `-e PILOTFISH_HEADLESS=1`。 。 。 .

### 代码 CLI

单位 `~/.codex/config.toml`数字 :

```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" }
```

### 光标、 Claude 桌面、 Windsurf等

在《诅咒》中 `~/.cursor/mcp.json` (或 `.cursor/mcp.json` 在一个项目中,克劳德桌面 `claude_desktop_config.json`,或者您的客户的等同:

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

设置在一个 `env` 对象旁边 `args`。 。 。 . `npx -y` 运行最新版本; 保留其中的编号 名称后( e)`@gaiventures/pilotfish-mcp@<version>`) (中文(简体) ). `npx -y @gaiventures/pilotfish-mcp --version` 打印 您的版本已经.

浏览器在自己的窗口中打开,当一个页面需要一个人时,在其中签名或解决一个CAPTCHA. `PILOTFISH_HEADLESS=1` 隐藏它; 在没有显示的 Linux 机器上, 它已经隐藏了 .

### 超过 HTTP

每个客户端共享一个浏览器,在127.0.0.1上:

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

使用 URL 的客户端 `"url": "http://127.0.0.1:8931/mcp"`。服务器只回答发送到 当地主机。 设定 `PILOTFISH_MCP_TOKEN` 要求 `Authorization: Bearer <token>`它必须服务于任何 其他地址。 .

## 工具

| 工具 | 它会做什么 |
| --- | --- |
| `browser_navigate` `{url, snapshot?}` | 打开一个 http(s) URL 并返回所发生事件加可见屏幕, 并计数上面和下面的内容 . `snapshot: false` 只返回已发生的事情和计数,以读取 `browser_query` 而不是采取行动. |
| `browser_snapshot` `{whole_page?}` | 该页作为紧凑的大纲,附有参考文献(第2页)`[e12]<button>Search`:大约在取景口周围有3个屏幕,或者全部用 `whole_page`。每个单词和注释都会被保留;重复的文本、关闭标记和生成的ID被忽略。 平面表行为一行,其单元格介于\` |
| `browser_click` `{ref}` | 单击元素。 被遮住,被遮住或看不见时拒绝. |
| `browser_type` `{ref, text, submit?}` | 替换字段文本 . `{{name}}` 键入已配置的秘密. |
| `browser_select` `{ref, values}` | 选择 `<select>` 选项. |
| `browser_press` `{key}` | 按键或快捷键( E)`Enter`, (中文(简体) ), `Escape`, (中文(简体) ), `Control+a`) (中文(简体) ). |
| `browser_scroll` `{direction}` | 卷起一屏而还. |
| `browser_actions` `{actions}` | 一个调用最多可有10个步骤,例如表单的字段及其提交按钮. 每个步骤 `{action, …}`数字 : `click`, (中文(简体) ), `type`, (中文(简体) ), `select`, (中文(简体) ), `press`, (中文(简体) ), `scroll` 或者说 `wait`,与自己的工具相同。 一个不正确的步骤在任何东西运行之前就停止了批量;否则它会停留在失败或移动到另一页的第一个步骤上. |
| `browser_query` `{expression}` | 以 JavaScript 表达式读取返回 JSON( 最多 4000 个字符): 一个结果,价格,计数的列表. 它不能单击、输入、提交或发送数据。 最便宜的读取一页. |
| `browser_find` `{query}` | 在页面的任意位置用他们的单词查找元素,最好先匹配. 用逗号分隔几个目标. |
| `browser_get_text` `{max_chars?, selector?}` | 页面的可读文本 (PDFs 也),或一个元素的可读文本 (`main`, (中文(简体) ), `#results`隐藏秘密 最多 `max_chars` (违约2万). |
| `browser_screenshot` `{}` | 一个JPEG的取景口。 秘密配置时关闭, 因为图像可以显示它们. |
| `browser_wait` `{seconds, until?, gone?}` | 等待多至0.5到10秒,然后返回改变的. 与 `until` 或者说 `gone` 它返回文本出现在页面或去时的瞬间(一个结果的标签,该网站的"计算"). 动作已经等待它们启动的请求, 等待一个页面从自己的 WebSocket 中获取答案, 等待一个加载行或倒计时站点显示 . |
| `browser_resume` `{timeout_s?}` | 听到结果后 `NEEDS A PERSON`: 等待( 默认 300 s) 直至您处理完页面, 然后返回 . |
| `browser_tabs` `{switch_to?}` | 列出打开的标签,或切换到 `switch_to: "t2"`。 。 。 . |
| `browser_close` `{}` | 关闭浏览器; 下一个调用打开一个新调用 。 结尾不需要:当客户端断开时关闭. |

## 如何表现

**每个屏幕一次.** 你的经纪人为它所读的每个信物付了钱 新的信物比它拥有的要贵得多 已经看过了 所以当特工在一页上行动时 它在最后8个结果中看到过 它只得到一条线 更改, 在其未更改的父行下分别标记 `~` ,其中删除的元素由参考文献列出。 校对器保持 在快照之间相同, 因此没有再次发送的行仍然有效 。 如果超过一半的屏幕被改变 整个屏幕,和 `browser_snapshot` 总是归还一切.

**需要一个人的页面.** 每次动作后,会检查页面 。 登录它没有资格,a 一次性代码或双因子快取、设备批准、登录链接、密码、三维安全或CAPTCHA `NEEDS A PERSON` 说明结果。 您在浏览器窗口处理它, 代理呼叫 `browser_resume`。 。 。 . pilotfish从未尝试通过这些页面本身:没有猜测的密码或代码,也没有CAPTCHA解析. 一个客户 支持引出 直接问你。 单靠自己清空的机器人检查首先要等出来,直到 12秒钟. `BLOCKED:` 表示网站拒绝了这个浏览器,并且 `STOP:` 标记一个不能自动化的网站.

**证实.** 看上去不可逆的行动(支付、发出命令、发送、删除)需要您同意。 一个客户端 诱导要求你;任何其他客户都会被拒绝行动,有原因.

## 设置

所有选择.

| 变量 | 默认 | 含义 |
| --- | --- | --- |
| `PILOTFISH_HEADLESS` | `0` 窗户可以打开,否则 `1` | `1` 隐藏浏览器窗口。 您无法用手签名或解决 CAPTCHA . |
| `PILOTFISH_ALLOWED_HOSTS` | 任何公共网站 | 逗号分隔主机名 : `*` 通配符( e)`example.com,*.example.com`) (中文(简体) ). |
| `PILOTFISH_ALLOW_PRIVATE` | `0` | `1` 允许本地主机和私人网络测试自己的应用程序. |
| `PILOTFISH_SECRETS` |  | JSON也一样 `{"name": "value"}` 或者说 `{"name": {"value"?, "totp"?, "allowedHosts"?}}`输入为 `{{name}}`; 基数32 `totp` 种子类型为当前二要素代码。 值从未到达模型,结果或出错. |
| `PILOTFISH_INTERVENTION_TIMEOUT_MS` | `180000` | 电话要等多久才能回答客户提出的问题. |
| `PILOTFISH_ALLOW_SCREENSHOTS` | 除非设置了秘密 | `1` 允许屏幕截图, 即使配置了秘密 . |
| `PILOTFISH_CHROME` | 自动查找 | 浏览器可执行文件的路径 . |
| `PILOTFISH_MCP_TOKEN` |  | HTTP模式:无记名符号客户端必须发送. |

有秘密的例子:

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

## 隐私

领航鱼只连接到您代理打开的网站,加上公共广告封条列表(EasyList、EasyPrivacy和EasyPrivacy) uBlock Origin的过滤器, 每周下载一次, 并缓存到 `~/.pilotfish/adblock`没有遥测,没有 飞行员服务器,没有模型供应商.

## 解决问题

-   **找不到铬可执行文件 :** 安装 Google Chrome, 或设置 `PILOTFISH_CHROME` 通往边缘Chrome的道路 或铬.
-   **服务器不启动于 Windows :** 开始 `npx` 结束 `cmd /c` (见上文Claude Code),并检查 `node --version` 22岁或更新.
-   **在您报名时, 一个呼叫时间 :** 将客户端的工具超时超过 300 秒( Codex : `tool_timeout_sec`自此以后 `browser_resume` 最多300 s给你.
-   **一个网站继续屏蔽浏览器 :** 这个软件包使用你自己的IP和一个平地Chrome,从不解决CAPTCHA. 清除浏览器窗口中的检查, 或者使用 [管理试验鱼](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp-managed)。 。 。 .

## 更多来自领航鱼

-   [管理试验鱼](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp-managed):云中全任务,, 签了你的名.
-   [试鱼软件](https://pilotfish.gai.ventures/):从网络运行任务,保存登录,观看直播,看到回放.

## 许可证

麻省理工学院

## 常见问题

### @gaiventures/pilotfish-mcp 是什么？

给任何MCP特工一个真正的Chrome在你自己的电脑上。 免费,没有账户,没有API密钥\. mcprush\.com-ba6a69f5121bd8a0089bb26a \(英语\)

### 如何安装 @gaiventures/pilotfish-mcp？

在项目目录运行 npm install @gaiventures/pilotfish-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 pilotfish-mcp，可以用 npx pilotfish-mcp 直接运行。

### @gaiventures/pilotfish-mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/gaiventures\_\_pilotfish-mcp 是否存在。

### @gaiventures/pilotfish-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gaiventures/pilotfish-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gaiventures/pilotfish-mcp 可以商用吗？

@gaiventures/pilotfish-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gaiventures/pilotfish-mcp 的下载量有多少？

根据 npm 官方下载统计，@gaiventures/pilotfish-mcp 在 2026/10/16 – 2026/11/14 这 30 天内被下载 10,337 次，日均约 345 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gaiventures/pilotfish-mcp 还在维护吗？

最新版本 0\.1\.50 发布于 2026/11/15（今天）；至今共发布 52 个版本，其中过去 12 个月发布了 52 个；首次发布于 2026/11/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。