chrome-pilot-mcp

English

通过 CDP（Chrome DevTools Protocol）连接已运行的 Chrome，并以 MCP 服务的形式暴露浏览器控制能力。

项目基于 patchright-core，适合需要保留登录态、Cookie、浏览器扩展和现有标签页的自动化场景。

核心特点

• 连接已有 Chrome 实例，无需重新启动浏览器。
• 保留登录态、用户数据和当前标签页上下文。
• 基于 patchright-core，尽量降低常见 CDP 自动化指纹。
• 提供连接、标签页、导航、交互、检视、表单等 18 个 MCP 工具。

安装

Claude Code（推荐）

# 全局安装
claude mcp add --scope user chrome-pilot -- npx -y chrome-pilot-mcp

# 项目级安装
claude mcp add --scope project chrome-pilot -- npx -y chrome-pilot-mcp

--scope user 写入 ~/.claude/settings.json，--scope project 写入 .claude/settings.local.json。

通过 npx 直接运行

npx -y chrome-pilot-mcp

手动配置

{
  "mcpServers": {
    "chrome-pilot": {
      "command": "npx",
      "args": ["-y", "chrome-pilot-mcp"]
    }
  }
}

从源码运行

git clone <repo-url>
cd chrome-pilot-mcp
npm install
npm run build
npm start

前置条件

Node.js / npx

npx 用于 Claude Code 启动 MCP 子进程。请先确认 Node.js 与 npx 可用（Node >= 18）：

node -v
npx -v

如果缺失可按平台安装 Node.js（安装后会包含 npx）：

# macOS
brew install node

# Ubuntu / Debian
sudo apt-get update && sudo apt-get install -y nodejs npm

# Windows (PowerShell)
winget install OpenJS.NodeJS.LTS

Chrome 版本

需要 Chrome >= 144，以支持通过 chrome://inspect/#remote-debugging 启用远程调试。

启用远程调试

在 Chrome 地址栏打开 chrome://inspect/#remote-debugging 并启用远程调试。Chrome 重启后通常需要重新启用。

DevToolsActivePort 路径

| 平台 | 路径 | | --- | --- | | macOS | ~/Library/Application Support/Google/Chrome/DevToolsActivePort | | Linux | ~/.config/google-chrome/DevToolsActivePort | | Windows | %LOCALAPPDATA%\\Google\\Chrome\\User Data\\DevToolsActivePort |

工具概览

| 类别 | 工具 | 用途 | | --- | --- | --- | | 连接 | chrome_status, chrome_connect, chrome_disconnect | 管理 Chrome 连接状态 | | 标签页 | chrome_list_tabs, chrome_select_tab, chrome_close_tab | 查看并切换标签页 | | 导航 | chrome_navigate, chrome_back, chrome_forward, chrome_reload | 执行页面导航 | | 交互 | chrome_click, chrome_type, chrome_scroll, chrome_press_key | 与页面元素交互 | | 检视 | chrome_screenshot, chrome_dump_dom, chrome_evaluate | 截图并检查页面状态 | | 表单 | chrome_fill_form, chrome_select_option | 批量填写表单 |

详细文档

• 中文使用手册：docs/usage.md
• English usage guide: docs/usage.en.md

License

MIT