pilot-mcp — Fast Browser Automation MCP Server

pilot — 面向 AI Agent 的浏览器自动化 MCP

默认使用由 Playwright 驱动的原生浏览器会话。QA 自动化无需 Chrome 扩展。

Pilot 提供两种浏览器后端：

• 原生模式（默认）：隔离的 Playwright 浏览器上下文。这是并行 QA 自动化和可靠截图的受支持方式。
• 扩展模式（旧版／可选启用）：连接到你的真实 Chrome 配置文件，以便使用现有 Cookie 和已登录的会话。

原生模式完全不使用 chrome.tabs.captureVisibleTab()，因此截图不受 Chrome 是否处于前台、标签页是否可见且处于活动状态，或扩展服务工作线程是否刚刚启动的影响。

---

工作原理

AI Agent → MCP Server → Broker on 127.0.0.1:3131 → Native browser session
         (stdio)       (first process owns broker)  (Playwright context/page)

1. Pilot 作为 MCP 服务运行 — Claude Code、Cursor 或任何 MCP 客户端通过 stdio 连接
2. 第一个 Pilot 进程成为本地主机上的代理
3. 后续 Pilot 进程作为代理客户端连接
4. 每个会话都拥有隔离的原生浏览器上下文／页面
5. 截图由 Playwright 获取，而不是通过 Chrome 扩展截图 API

---

快速开始

1. 添加 MCP 服务

codex mcp add pilot \
  --env PILOT_BROWSER_MODE=native \
  --env PILOT_PROFILE=full \
  -- npx -y pilot-mcp

对于本地检出：

npm install
npm run build
codex mcp add pilot \
  --env PILOT_BROWSER_MODE=native \
  --env PILOT_PROFILE=full \
  -- node /absolute/path/to/pilot/dist/index.js

2. 开始使用

“打开 https://example.com，截一张图，并总结页面内容。”

无需安装扩展，也不要求 Chrome 处于前台。

有关原生模式操作、压力测试命令和清理检查的完整说明，请参阅 docs/native-mode.md。

---

精简快照

其他工具会将每个页面中超过 50K 个字符的内容转储到上下文窗口。Pilot 会控制内容长度：

Other tools:   navigate(58K) → navigate(58K) → answer        = 116K chars
Pilot:         navigate(2K)  → navigate(2K)  → snapshot(9K)  =  13K chars

snapshot_diff 仅显示操作之间发生的变化，不会重复读取未更改的内容。

上下文更少 = 响应更快、API 调用成本更低、幻觉更少。

---

Pilot 与 @playwright/mcp 对比

	Pilot	@playwright/mcp
浏览器	默认使用原生 Playwright 上下文；通过旧版扩展连接真实 Chrome	新建 Chromium 实例
认证状态	默认隔离的原生环境；扩展模式可使用真实 Chrome Cookie	匿名 — 需手动设置
机器人检测	自动化使用原生模式；真实配置文件交接使用扩展模式	被 Cloudflare 拦截
快照大小	导航约 2K，完整快照约 9K	约 50-60K
快照差异	pilot_snapshot_diff	❌
Cookie 导入	Chrome、Arc、Brave、Edge、Comet	手动导入 JSON
iframe	✅	❌
工具配置	core（9 个）／standard（40 个）／full（69 个）	--caps 分组
传输方式	stdio	stdio、HTTP、SSE

---

3 种配置，涵盖 69 个工具

工具列表越长，大模型的表现越差。只加载你需要的内容：

配置	工具数	包含内容
core	9	navigate、snapshot、click、fill、type、press_key、wait、screenshot、snapshot_diff
standard	40	Core + pilot_act、pilot_guide、evidence、doctor/reset、tabs、scroll、hover、drag、iframes、auth、block、find
full	69	Standard + 网络拦截、断言、剪贴板、地理位置、CDP、evaluate、PDF、响应式、深度检查

{
  "mcpServers": {
    "pilot": {
      "command": "npx",
      "args": ["-y", "pilot-mcp"],
      "env": { "PILOT_PROFILE": "standard" }
    }
  }
}

默认配置：standard。完整工具参考 →

---

原生模式

原生模式为默认模式：

PILOT_BROWSER_MODE=native

适用于 QA 自动化、并行 MCP 会话和截图取证。

在 QA 运行前验证：

PILOT_HEADLESS=1 npm run stress:screenshots
npm run stress:codex

预期结果：两者均报告 6/6 passed。

扩展模式

扩展模式为旧版功能，默认不启用：

PILOT_BROWSER_MODE=extension

仅当你需要使用用户已通过身份验证的真实 Chrome 配置文件时，才使用此模式。

从真实浏览器导入 Cookie：pilot_import_cookies({ browser: "chrome", domains: [".github.com"] })

支持通过 macOS Keychain / Linux libsecret 使用 Chrome、Arc、Brave、Edge、Comet。遇到 CAPTCHA 时：pilot_handoff → 你进行处理 → pilot_resume。

---

要求

• Node.js >= 18
• Playwright Chromium
• macOS 或 Linux
• 仅扩展模式：Chrome + Pilot 扩展

如果缺少 Chromium：

npx playwright install chromium

安全性

• 扩展仅通过 localhost（127.0.0.1）通信
• 原生代理仅通过 localhost（127.0.0.1）通信
• 每个 MCP 会话的原生会话都使用隔离的浏览器上下文
• 输出路径验证可防止在 PILOT_OUTPUT_DIR 之外写入文件
• 所有文件操作均提供路径遍历保护
• PILOT_PROFILE 控制要公开哪些工具（core / standard / full）

---

致谢

核心架构——基于引用的元素选择、快照差异比较和带注释的屏幕截图——移植自 Garry Tan 的 gstack。基于 Playwright 和 MCP SDK 构建。

---

如果 Pilot 对你有帮助，请为仓库点亮星标，这能帮助其他人发现它。