使用说明

铬醇mcp

🌐 英文版Readme

通过自然语言实现人工智能驱动的Chrome自动化。 不再与CSS选择器、XPath表达式或脆弱的测试脚本发生冲突。只需告诉你的AI助手你想在网页上做什么，ChromeTools MCP就会实现。

为什么选择ChromeTools MCP？

对于AI代理和开发人员：

🎯 56+专用工具 用于浏览器自动化-从简单的点击到Figma比较
🧠 APOM（代理页面对象模型） -AI友好的页面表示（约8-10k代币，而截图为5-10k代币）
🔄 持续浏览器会话 -页面在迭代工作流的命令之间保持打开状态
⚡ 框架感知 -自动处理React、Vue、Angular事件和状态更新
📸 目视检测 -用Figma积分逐像素比较设计
🎬 场景录制 -记录浏览器操作、回放或导出为Playwright/Senium测试
🌍 跨平台 -在Windows、WSL、Linux和macOS上无缝工作

非常适合：

🤖 构建与web应用程序交互的AI代理
🧪 无需编写代码的自动化测试-让AI从场景中生成测试
🔍 使用自然语言指令进行网络抓取和数据提取
🎨 设计验证-将实现的UI与Figma设计进行比较
🚀 快速原型制作——通过向人工智能描述用户流来测试用户流
📊 web应用程序的监控和健康检查

停止编写脆弱的自动化脚本。开始用简单的英语描述你想要什么。

安装

克劳德代码（CLI）

对于Claude Code用户来说，最简单的安装方法是：

claude mcp add chrometools -- npx chrometools-mcp

此命令将在您的Claude Code设置中自动配置MCP服务器。

克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS/Linux： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"]
    }
  }
}

光标

第一步： 在光标中打开MCP设置

点击设置 (⚙️ 图标或 Cmd + , / Ctrl + ,)
导航至 光标设置 → 主控程序

第二步： 编辑MCP配置

您将看到MCP配置JSON编辑器
添加 chrometools 到 mcpServers 对象：

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"]
    }
  }
}

如果您已经配置了其他MCP服务器，只需将chrometools添加到现有列表中：

{
  "mcpServers": {
    "existing-server": {
      "command": "npx",
      "args": ["some-other-mcp"]
    },
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"]
    }
  }
}

步骤3： 保存并重新启动

保存配置文件
重新启动Cursor以应用更改
chrometools mcp工具现在可以在Cursor Agent中使用

步骤4： 测试安装

打开光标聊天
选择代理模式
尝试以下命令：“打开浏览器并导航到google.com”

谷歌反重力

第一步： Antigravity中的开放代理会话

第二步： 点击“…“编辑器侧面板顶部的下拉菜单

步骤3： 选择 “MCP服务器” 打开MCP商店

步骤4： 点击 “管理MCP服务器” 位于MCP商店的顶部

步骤5： 点击 “查看原始配置” 在主选项卡中

步骤6： 编辑 mcp_config.json （位于 ~/.gemini/antigravity/ 目录）：

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"]
    }
  }
}

步骤7： 保存文件并重新启动Antigravity

注：反重力每次会话限制约100个工具。如果您安装了许多MCP服务器，请考虑将活动工具的数量减少到约25个，以获得最佳性能。

其他MCP客户端

对于Cline、Continue或其他MCP兼容客户端，请在MCP配置中添加：

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"]
    }
  }
}

手动安装

您也可以直接运行而无需配置：

npx chrometools-mcp

Chrome扩展程序设置

Chrome扩展程序是 必需的 用于场景录制和其他高级功能。请按照以下步骤进行安装：

重要提示： ChromeTools使用单独的用户配置文件打开Chrome，因此您必须安装扩展程序之后 ChromeTools首次启动Chrome。

第一步： 首先启动ChromeTools MCP服务器

确保ChromeTools正在通过您的MCP客户端（Claude Desktop、Cursor等）运行
或者手动运行它： npx chrometools-mcp
这将启动带有ChromeTools独立配置文件的Chrome

第二步： 在Chrome中启用开发者模式

打开Chrome扩展程序页面： chrome://extensions
切换 开发者模式 （右上角开关）

步骤3： 下载并解压扩展

选项A-从GitHub下载（推荐）：

下载扩展存档： chrome-extension.zip
将ZIP文件解压缩到计算机上的文件夹中
记住提取路径（下一步需要它）

选项B-从node_modules使用（如果你知道路径）：

安装npx后： ~/.npm/_npx/.../node_modules/chrometools-mcp/extension
全局安装后： <npm-global-path>/node_modules/chrometools-mcp/extension
来源： <repo-path>/extension

步骤4： 加载扩展

点击 “未包装装载” 按钮
导航到提取的扩展文件夹（从步骤3开始）
选择文件夹并单击 “选择文件夹”

步骤5： 验证安装

您应该看到“ChromeTools MCP”扩展出现在您的扩展列表中：
- 姓名： ChromeTools MCP
- 版本： （当前版本）
- 说明： 用于Chrome自动化的MCP服务器集成
- 状态： 开关应打开（蓝色）
在Chrome工具栏中查找ChromeTools图标（CT）
该扩展现在已准备好用于场景录制

注：安装后，扩展卡将出现在 chrome://extensions 页面旁边还有其他已安装的扩展。扩展应显示为“已启用”，并带有蓝色切换开关。

步骤6： 固定扩展（可选但推荐）

点击Chrome工具栏中的拼图图标
在列表中找到“ChromeTools MCP”
单击图钉图标，使其在工具栏中可见

故障排除：

推荐： 使用选项A（从GitHub下载）避免在node_modules中搜索
如果使用选项B后找不到扩展文件夹 npx 安装，运行 npm list -g chrometools-mcp 查找安装路径
该扩展程序仅适用于ChromeTools启动的Chrome实例
如果Chrome关闭并重新打开，扩展程序仍应加载（开发人员模式仍然存在）
当ChromeTools首次打开Chrome时，它会自动在node_modules中显示一个包含扩展路径的提示

安装
- Chrome扩展程序设置
AI优化功能- 场景记录器 -基于可视化UI的录制，具有智能优化功能
可用工具 - 51+工具总计
- AI驱动的工具 -smartFindElement、analyzePage、getElementDetails、findElementsByText
- 核心工具 -ping，打开浏览器
- 交互工具 -单击、键入、滚动到、选择选项、选择从组、拖动、滚动水平
- 检测工具 -getElement、getComputedCss、getBoxModel、屏幕截图
- 高级工具 -executeScript、getConsoleLogs、listNetworkRequests、getNetworkRequest、filterNetworkRequest、悬停、按键、setStyles、setViewport、getViewport、navigation
- 选项卡管理工具 -listTabs，switchTab
- 框架工具 -listFrames，switchFrame（跨源iframe自动化）
- 记录器工具 -enableRecorder、executeScenario、listScenarios、searchScenario，getScenarioInfo、deleteScenario和exportScenarioAsCode，append ScenarioToFile，generatePageObject
- API/Swagger工具 -loadSwagger，generateAPI模型
典型工作流示例
工具使用提示
配置
多实例支持 -同时运行多个MCP服务器
WSL设置指南 → WSL完整指南
发展
特征
建筑

AI优化功能

：通过智能元素查找和页面分析，大大缩短了AI代理的请求周期。

为什么这很重要

使用AI的传统浏览器自动化需要许多试错周期：

AI: "Find login button"
→ Try selector #1: Not found
→ Try selector #2: Not found
→ Try selector #3: Found! (3 requests, 15-30 seconds)

通过AI优化：

AI: smartFindElement("login button")
→ Returns ranked candidates with confidence scores (1 request, 2 seconds)

主要特点

analyzePage - 🔥 经常使用 -加载、点击、提交后获取当前页面状态（缓存，使用refresh：true）
smartFindElement -支持多语言的自然语言元素搜索
AI提示 -所有工具中的自动上下文（页面类型、页面标题、模态内容、下拉/菜单项、建议）
文本搜索 - findElementsByText 用于通过可见文本查找元素

演出速度提高3-5倍，请求减少5-10倍

最佳实践：

使用 analyzePage() 页面加载后和交互（点击、提交）后
使用 analyzePage({ refresh: true }) 页面更改后查看当前状态
更喜欢 analyzePage 结束 screenshot 用于调试表单数据

📚 完整的AI优化指南

场景记录器

：基于可视化UI的记录器，用于创建具有自动秘密检测功能的可重用测试场景。

特征

可视化小部件 -具有紧凑模式的浮动记录器UI（50x50px最小化按钮）
自动回注 -记录器在页面重新加载/导航过程中自动保持不变，防止重复- 智能点击检测 -使用事件侦听器查找实际可点击的父元素- 智能服务员 -点击后2秒最小+动画/网络/DOM变化检测- 详细错误报告 -带上下文和建议的全面故障分析- 智能录音 -通过智能优化捕获点击、打字和导航
秘密侦查 -自动检测密码/电子邮件并安全存储
动作优化 -组合顺序操作，删除重复项
场景管理 -保存、加载、执行、搜索和删除场景
依赖项 -将场景与依赖关系解决链接在一起
多实例保护 -防止多个记录器实例相互干扰

快速开始

// 1. Enable recorder UI
enableRecorder()

// 2. Click "Start" in widget, perform actions, click "Stop & Save"
// 3. Execute saved scenario
executeScenario({ name: "login_flow", parameters: { email: "user@test.com" } })

📚 完整录音指南 | 记录器规格

可用工具

⚠️ 工具使用优先级

关键：始终先使用专用工具。永远不要跳到 executeScript 作为第一选择。

用于点击/交互

✅ click() -用于所有点击的主工具
- 与React/Vue/Angular合成事件正确配合使用
- 处理按钮点击、链接导航、表单提交
✅ findElementsByText() +行动 -当选择器未知时，按文本查找
⚠️ executeScript() -只有在上述失败的情况下，才采取最后手段

用于填写表格

✅ type() -用于所有文本输入的主工具
- 正确更新React挂钩、Vue响应式数据
- 键入前自动清除字段（可配置）
⚠️ executeScript() -只有在上述失败的情况下，才采取最后手段

用于读取页面状态

✅ analyzePage() -阅读页面内容的主要工具
- 获取具有当前值的窗体、输入、按钮和链接
- 使用 refresh: true 交互后查看更新状态
- 高效：2-5k代币vs截图5-10k
✅ findElementsByText() -通过可见文本查找特定元素
✅ getElement() -获取特定元素的HTML
⚠️ executeScript() -只有在上述失败的情况下，才采取最后手段

基于模型的交互（高级）

✅ executeModelAction() -用于模型特定操作的通用工具
- 使用元素模型（策略模式）
- 支持APOM ID和CSS选择器
- 特定于框架的操作（例如，DatePicker设置日期、复选框切换）
- 例子： executeModelAction({id: "input_34", action: "check"})
- 例子： executeModelAction({selector: ".datepicker", action: "SetDate", params: {date: "2024-03-15"}})
- 看 models/ 可用模型和操作目录
- 可用型号：TxtInp、Sel、Btn、Chk、Radio、TxtArea、Link、Range、DatePicker、DateInp、FileInp、ColorInp、，模态，默认值

模态/对话支持

自动检测：APOM检测通过React门户呈现的模态（antd、MUI、Bootstrap、Chakra、Mantine、Element UI、Headless UI、Radix）
检测方法: role="dialog", aria-modal="true"，框架特定的CSS类
动画证明：即使在CSS显示动画期间也包含模态元素（不透明度：0）
元数据：模态节点包括 title 和 actions 元数据中的（按钮标签）
在APOM树上：模态显示为 type: "dialog" 随着 model: "Modal"，包含所有互动儿童

为什么专业工具很重要：

✅ 触发适当的浏览器事件（点击、输入、更改）
✅ 使用React/Vue/Angular合成事件系统
✅ 正确更新框架状态（React钩子、Vue反应性）
✅ 处理动画、导航和异步更新
❌ executeScript 绕过框架事件，可能会自动失败

AI驱动的工具

smartFindElementFind使用自然语言描述而不是CSS选择器查找元素。

参数:
- description （必填）：自然语言（例如“登录按钮”、“电子邮件字段”）
- maxResults （可选）：返回的最大候选人数（默认值：5）
- minConfidence （可选）：置信阈值（0-1，默认值 0.6)用于自动执行 action如果最好的比赛得分低于此，或者太接近亚军，则采取行动跳过候选人将获得 actionSkipped 相反，原因。防止自动单击错误的控件（例如，当您要求菜单项时，主表单提交）。降低它以对较弱的比赛采取行动。
候选人覆盖率：除此之外 button/input/a/[role=button]，还考虑 [onclick], [role=menuitem], [role=tab]，以及内部链接 nav/[role=navigation]/[role=menu] --因此，菜单项呈现为 div/span[onclick] 被发现。评分会惩罚文本与描述不匹配的候选人，并奖励导航/菜单上下文。
用例：当你不知道确切的选择器时
退货：根据信心评分、选择者和推理能力对候选人进行排名

示例:

{
  "description": "submit button",
  "maxResults": 3
}

退货：

{
  "candidates": [
    { "selector": "button.login-btn", "confidence": 0.95, "text": "Login", "reason": "type=submit, in form, matching keyword" },
    { "selector": "#submit", "confidence": 0.7, "text": "Send", "reason": "submit class" }
  ],
  "hints": { "suggestion": "Use selector: button.login-btn" }
}

analyzePage获取当前页面状态和结构。返回表单（带值）、输入、按钮、带选择器的链接的完整映射。

交互检测:

通过以下方式检测交互元素 8种不同的方法:
1. 原生HTML标签(button, a, input, select, textarea)
2. ARIA角色(button, link, checkbox等等）
3. onclick 属性
4. onclick 属性（通过JavaScript设置）
5. 层叠样式表 cursor: pointer
6. JavaScript addEventListener('click')
7. tabindex 属性（-1除外）
8. contenteditable="true"
使用点击处理程序捕获DIV/SPAN -检测到启用JavaScript的元素
添加 interactivityReason 显示检测方法的元数据（例如。， cursor-pointer, event-listener)

何时使用:

打开/导航到页面后（初步分析）
点击按钮后 （看看有什么变化）
提交表格后 （检查结果、错误）
AJAX更新后 （加载动态内容）
调试时（查看实际表单值，而不仅仅是视觉值）
布局/造型工作 -使用 includeAll: true 使用选择器获取所有页面元素
参数:
- refresh （可选）：更改后强制刷新缓存以获取当前状态（默认值：false）
- includeAll （可选）：包括所有页面元素，而不仅仅是交互式元素（默认值：false）。对布局工作很有用-找到任何元素，获取其选择器，然后使用 getComputedCss 或 setStyles 在上面。
- useLegacyFormat （可选）：返回传统格式而不是APOM（默认值：false-默认值为APOM）
- registerElements （可选）：自动注册元素以用于基于ID的使用（默认值：true）- groupBy （可选）：'type'或'flat'-如何对元素进行分组（默认值：'type]）
- includePortals （可选）：包括React Portal容器的内容——菜单、工具提示、在主React根之外呈现的弹出窗口（默认值： true).如果没有这个，下拉窗口中的项目（例如MTS类应用程序中的操作菜单）对用户是不可见的 analyzePage.
- portalSelectors （可选）：门户根容器的CSS选择器数组。违约： ['#modal-root', '#menu-popup-root', '#tooltip-root', '#popover-root', '[data-portal]']。当应用程序使用不同的门户元素ID时，进行覆盖。
- 树内弹出启发式：当 includePortals 启用（默认）， analyzePage 还可以检测“树内门户”模式——在0高度内联包装器内呈现的弹出窗口，并在其中绝对定位（Popper、Tippy、FloatingUI、自定义contextMenu实现）。没有这个，弹出项目就存在于 offsetHeight: 0 包装这个 isVisible drops，使整个弹出子树对不可见 analyzePage. - 为什么比截图更好:
- 显示实际数据（表单值、验证错误），而不仅仅是视觉数据
- 使用2-5k代币，而截图使用5-10k代币
- 返回结构化数据 唯一元素ID 便于交互
- 检测UI框架 （MUI、蚂蚁设计、Chakra、Bootstrap、Vuetify、语义UI）- 提取下拉选项 来自两个本地 <select> 以及自定义UI组件- 退货:
- APOM格式 （默认）：具有唯一ID的树结构页面对象模型- tree -页面元素的层次树（优化：比平面格式小约82%）
  - 每个节点： { tag, id?, type?, sel, ch?, bounds?, meta? }
  - 互动元素有 bounds 完整元数据
  - 父容器具有最少的信息（仅位置）
  - groups -带有选项（名称、值、标签、选中状态）的单选/复选框组
  - meta -页面元数据（url、标题、时间戳、元素计数）
  - 元素自动注册-使用ID click({ id: "..." }), type({ id: "..." })等等。
  - 令牌优化：压缩JSON，简化父数据，无冗余数据
  - 例子： analyzePage() 返回APOM，然后使用 click({ id: "button_45" }) 或 type({ id: "input_20", text: "..." })
- 使用 getElementDetails({ id: "input_20" }) 获取任何元素的完整细节，或 analyzeChildren: true 获取子树结构
- 遗留格式 (useLegacyFormat: true)：经典格式，向后兼容
  - 表单（带当前值）、输入、按钮、链接、带选择器的导航的完整地图
  - 每个元素包括 uiFramework 信息 （名称、版本、组件类型）- 选择的元素包括 options 数组 带值、文本、索引、选中、禁用、分组-带 includeAll: true：还包括 allElements 包含所有可见页面元素（div、span、标题等）的数组，每个元素都有选择器、标签、文本、类、id
工作流程示例:
1. openBrowser({ url: "..." })
2. analyzePage() ← 初始分析，返回带有ID的元素
3. type({ id: "input_20", text: "user@example.com" }) ← 使用APOM ID
4. click({ id: "button_45" }) ← 使用APOM ID
5. analyzePage({ refresh: true }) ← 看看点击后发生了什么变化！
布局工作示例:
1. analyzePage({ includeAll: true }) ← 获取所有元素
2. 找到你想要设计风格的元素（例如。， div.header)
3. getComputedCss({ selector: "div.header" }) ← 获取当前样式
4. setStyles({ selector: "div.header", styles: [...] }) ← 应用新样式

getElementDetails通过APOM ID获取特定元素的全面详细信息。可以选择分析子元素树结构。使用时 `analyzePage` 输出被简化，您需要完整的元素信息或希望将分析重点放在特定部分。

参数:
- id （必填）：APOM元素ID（例如。， "input_20", "button_45")
- analyzeChildren （可选）：分析子元素树结构（默认值：false）
- includeAll （可选）：分析子元素时，包括所有元素，而不仅仅是交互式元素（默认值：false）
- refresh （可选）：强制刷新缓存的分析（默认值：false）
用例:
- 获取完整的细节，包括边界、CSS选择器、属性、计算样式
- 重点分析特定部分（模态、形式、侧边栏等） analyzeChildren: true
退货：完整的元素细节，包括：
- id：元素APOM ID
- selector：元素的CSS选择器
- tag：HTML标记名称
- type：元素类型（输入、按钮、链接等）
- text：可见文本内容
- bounds：位置和尺寸 { x, y, width, height, top, right, bottom, left }
- attributes：所有HTML属性（id、类、名称、占位符、href等）
- computed：关键CSS属性（显示、可见性、光标、颜色、字体大小等）
- metadata：来自APOM分析的元素元数据
- visible：元素是否可见
- childrenTree （可选）：APOM树结构时的子元素 analyzeChildren: true

示例:

// Get complete details for specific input field
getElementDetails({ id: "input_20" })

// Returns:
{
  "success": true,
  "id": "input_20",
  "selector": "input[name='email']",
  "tag": "input",
  "type": "email",
  "text": "",
  "bounds": { "x": 100, "y": 200, "width": 300, "height": 40, "top": 200, "right": 400, "bottom": 240, "left": 100 },
  "attributes": { "name": "email", "placeholder": "Enter email", "type": "email" },
  "computed": { "display": "block", "visibility": "visible", "cursor": "text" },
  "visible": true
}

// Analyze modal contents after opening it
analyzePage() // Get initial page structure
click({ id: "button_45" }) // Open modal
getElementDetails({ id: "container_123", analyzeChildren: true, refresh: true }) // Analyze modal contents with children tree

findElementsByText

根据可见文本内容查找元素。

参数:
- text （必填）：要搜索的文本
- exact （可选）：仅完全匹配（默认值：false）
- caseSensitive （可选）：区分大小写的搜索（默认值：false）
退货：包含文本及其选择器的元素

1.核心工具

拼

使用简单的乒乓响应测试MCP连接。

参数: message （可选）
示例: { "name": "ping", "arguments": { "message": "hello" } }
退货: pong: hello

打开浏览器

打开浏览器并导航到URL。浏览器保持打开状态以进行进一步交互。

参数: url （必填）
用例：其他工具之前的第一步
退货：页面标题+确认

2.交互工具

点击

单击带有可选结果屏幕截图的元素。首选：使用来自的APOM ID analyzePage 为了实现可靠的目标定位。

参数:
- id （可选）：来自analyzePage的APOM元素ID（例如。， "button_45", "link_7"). 比选择器更受欢迎。
- selector （可选）：CSS选择器。当APOM ID不可用时使用。
- ⚠️ 要么 id 或 selector 必需（互斥）
- waitAfter （可选）：等待时间（毫秒）（默认值：1500）
- screenshot （可选）：捕获屏幕截图（默认值：性能为false）⚡
- timeout （可选）：最大操作时间（毫秒）（默认值：30000）
- skipNetworkWait （可选）：跳过等待网络请求（默认值：false）。 用于具有连续长轮询的页面，以获得即时响应。
- networkWaitTimeout （可选）：自定义网络等待超时（毫秒）（默认值：10000）。仅在skipNetworkWait为false时使用。
- waitForSelector （可选）：要等待的CSS选择器之后单击--原子单击+等待。用于渲染到React门户中的下拉菜单/弹出窗口，否则将与下一个MCP调用竞争。例子： click({ id: 'button_47', waitForSelector: '#menu-popup-root > div' }).
- waitTimeoutMs （可选）：超时 waitForSelector 单位为毫秒（默认值：2000）。超时后，点击仍然成功，但结果文本会报告 ⚠️ WAIT_TIMEOUT.
- waitForRouteChange （可选）：用于SPA（React Router等）。点击后，等待 location.pathname + location.search 相对于之前进行更改，然后报告 Route changed: "/a" → "/b" 或 ⚠️ ROUTE_UNCHANGED。因为SPA通过以下方式导航 history.pushState，简单的网络诊断可能不会注册导航——这使得“成功”意味着视图实际发生了变化，而不仅仅是点击成功。点击超时永不失败。对于不改变URL的视图更改，请使用 waitForSelector 相反。
- autoAnalyzeAfter （可选）：单击后，自动区分APOM并将增量附加到结果文本中（例如。 +3 appeared: button_42:"Статистика", button_43:"Настройки", link_44:"Удалить").新元素ID已预先注册，因此下一个 click({ id })/type({ id }) 通话成功 没有额外的 analyzePage.设计用于下拉/菜单模式：一个MCP调用而不是三个。
用例：按钮、链接、表单提交、Django管理表单
退货：确认文本+可选屏幕截图+网络诊断
演出：无需屏幕截图，使用skipNetworkWait即可即时运行，速度提高2-10倍
点击策略：三层回退以实现最大兼容性：
1. Puppeter原生点击（受信任的CDP事件）
2. CDP坐标点击元素中心（可信，绕过拦截检查）
3. JavaScript element.click() （不可信，最后手段）

示例:

// PREFERRED: Using APOM ID
click({ id: "button_45" })

// Alternative: Using CSS selector
click({ selector: "button[type='submit']" })

// Django forms with WebSockets (prevents timeout)
click({ selector: ".submit-row input[type='submit']", skipNetworkWait: true })

// Custom network timeout for slow APIs
click({ id: "save_btn", networkWaitTimeout: 10000 })

类型

在输入字段中键入文本，并可选择清除和键入延迟。首选：使用来自的APOM ID analyzePage 为了实现可靠的目标定位。

参数:
- id （可选）：来自analyzePage的APOM元素ID（例如。， "input_20"). 比选择器更受欢迎。
- selector （可选）：CSS选择器。当APOM ID不可用时使用。
- ⚠️ 要么 id 或 selector 必需（互斥）
- text （必填）：键入文本
- delay （可选）：按键之间的延迟（毫秒）（默认值：30）
- clearFirst （可选）：先清除字段（默认值：true）
- timeout （可选）：最大操作时间（毫秒）（默认值：30000）。 防止Django窗体上的无限挂起。
用例：填写表单、搜索框、文本输入、Django管理表单
退货：确认文本

示例:

// PREFERRED: Using APOM ID
type({ id: "input_20", text: "user@example.com" })

// Alternative: Using CSS selector
type({ selector: "input[name='email']", text: "user@example.com" })

滚动到

滚动页面以查看元素。

参数:
- selector （必填）：CSS选择器
- behavior （可选）：“自动”或“平滑”
用例：延迟加载、粘性元素、可见性检查
退货：最终滚动位置

选择选项

在下拉菜单中选择选项（HTML选择元素）。首选：使用来自的APOM ID analyzePage 为了实现可靠的目标定位。

参数:
- id （可选）：来自analyzePage的APOM元素ID（例如。， "select_5"). 比选择器更受欢迎。
- selector （可选）：CSS选择器。当APOM ID不可用时使用。
- ⚠️ 要么 id 或 selector 必需（互斥）
- value （可选）：选项值属性（优先级1）
- text （可选）：选项文本内容（优先级2）
- index （可选）：选项索引，从0开始（优先级3）
用例：表单下拉菜单、筛选菜单、选择菜单
退货：所选选项详细信息（值、文本、索引）
选择优先级：如果指定了多个参数，则尝试值→ text → index
人工智能集成：使用 analyzePage 查看所有可用选项及其值、文本和索引

示例:

// PREFERRED: Using APOM ID
selectOption({ id: "select_5", value: "US" })

// Alternative: Using CSS selector
selectOption({ selector: "select[name='country']", text: "United States" })

selectFromGroup从单选框或复选框组中按名称属性选择选项。在抽象组级别工作，而不是单独点击。

参数:
- name （必填）：单选/复选框组的名称属性（例如，“大小”、“顶部”）
- value （可选）：选择单个值（用于单选或单个复选框）
- values （可选）：要选择的值数组（用于复选框组）
- text （可选）：要匹配的标签文本（值的替代）
- texts （可选）：要匹配的标签文本数组（用于复选框组）
- by （可选）：按“值”、“文本”或“自动”匹配（默认值：“自动”）
- mode （可选）：复选框-“设置”（全部替换）、“添加”、“删除”、“切换”（默认值：“设置”）
用例：单选按钮、复选框组、表单选项
退货：所做更改和当前选择状态的结果
人工智能集成：使用 analyzePage 查看中的可用组 groups 包含所有选项和标签的部分

例子:

// Radio group - select single option
selectFromGroup({ name: "size", value: "large" })
selectFromGroup({ name: "size", text: "Extra Large" })

// Checkbox group - set specific values (uncheck others)
selectFromGroup({ name: "toppings", values: ["cheese", "bacon"] })

// Checkbox group - add to existing selection
selectFromGroup({ name: "toppings", values: ["mushrooms"], mode: "add" })

// Checkbox group - remove specific values
selectFromGroup({ name: "toppings", values: ["onions"], mode: "remove" })

// Checkbox group - toggle values
selectFromGroup({ name: "toppings", texts: ["Extra Cheese"], mode: "toggle" })

拖拽

用鼠标拖动元素（单击、按住、移动、释放）。模拟真实的鼠标拖动，而不是滚动条滚动。

参数:
- selector （必填）：用于拖动元素的CSS选择器
- direction （必填）：“向上”、“向下”、“向左”、“向右”、“左上”、
- distance （可选）：距离（像素）（默认值：100）
- duration （可选）：拖动持续时间（毫秒）（默认值：500）
- mode （可选）：“原生”（默认）或“合成”
  - “本地”：使用Puppeteer鼠标API-速度更快，适用于大多数情况
  - “合成”：分派DOM事件（pointerdown/pointermove/pointerup）-更好地兼容JS库（frappe gantt、jQuery UI Draggable、自定义拖动处理程序）
用例：交互式地图（谷歌地图、传单）、甘特图、SVG图、画布元素、滑块、拖放界面
运作原理:
- 原生模式：使用Puppeteer的鼠标API（mousedown→ 鼠标移动→ 鼠标悬停）
- 合成模式：在拖动过程中，在具有中间点移动事件的元素上分派PointerEvent/MouseEvent
何时使用合成模式：如果原生拖动没有触发JS库事件处理程序（例如frappe gantt、jQuery UI、React DnD）
不是为了：标准溢出滚动条（使用 scrollTo 或 scrollHorizontal 相反）
退货：开始/结束鼠标位置、拖动增量和使用的模式

水平滚动

水平滚动元素（用于表格、旋转木马、宽内容）。

参数:
- selector （必填）：用于滚动元素的CSS选择器
- direction （必填）：“左”或“右”
- amount （必填）：要滚动的像素数，或滚动到末尾的“满”像素数
- behavior （可选）：自动或平滑（默认：自动）
用例：宽桌子、图像旋转木马、可水平滚动的容器
退货：滚动状态（位置、总宽度、可见宽度、滚动可用性）

3.检查工具

获取元素

获取元素的HTML标记（如果没有选择器，则默认为body）。

参数: selector （可选）
用例：检查结构、调试标记
退货：完成outerHTML

getComputedCss

通过智能过滤获取元素的计算CSS样式，以减少令牌使用。

参数:
- selector （可选）：CSS选择器（默认为body）
- category （可选）：按类别筛选-“布局”、“排版”、“颜色”、“视觉”或“全部”（默认）
- properties （可选）：要返回的特定属性数组（例如。， ['color', 'font-size'])-覆盖类别筛选器
- includeDefaults （可选）：包含具有默认值的属性（默认值：false）
用例：调试布局、验证样式、设计比较
退货：具有过滤CSS属性的JSON对象，关于过滤的元数据
演出：不使用过滤器将返回约300个属性（约14k令牌）。过滤返回10-50个属性（~1-2k令牌）
示例用法:
- 仅布局： { selector: ".header", category: "layout" }
- 具体属性： { selector: ".title", properties: ["color", "font-size", "font-weight"] }
- 无默认值的排版： { selector: "h1", category: "typography", includeDefaults: false }

getBox模型

获得精确的尺寸、位置、边距、填充和边框。

参数: selector （必填）
用例：像素完美测量、布局分析
退货：盒子模型数据+指标

截图

捕获特定元素的优化屏幕截图，或在没有时捕获整个视口 id/selector 已给出。智能压缩，硬限制为3 MB。

参数:
- id （可选）：APOM元素ID来自 analyzePage.相互排斥 selector.
- selector （可选）：CSS选择器。相互排斥 id.
- 两者都省略 id 和 selector 捕捉 全视口 （不需要元素分辨率）。
- padding （可选）：填充像素（默认值：0）。视口屏幕截图忽略。
- maxWidth （可选）：自动缩放的最大宽度（默认值：1024，原始大小为空）
- maxHeight （可选）：自动缩放的最大高度（默认值：8000，原始大小为空）
- quality （可选）：JPEG质量1-100（默认值：40）
- format （可选）：“png”、“jpeg”或“auto”（默认值：“jpeg”）
用例：可视化文档、错误报告
退货：使用元数据优化图像（~5-10k令牌）
默认行为：JPEG，质量为40，自动缩放至1024px宽和8000px高（API限制）。为了获得更高的质量，请明确设置 quality 和 format 参数
自动压缩：如果图像超过3 MB，则会自动降低质量或缩小以适应限制
对于原始质量：设置 maxWidth: null, maxHeight: null 和 format: 'png' （仍然执行3MB限制）

保存屏幕截图

将优化后的屏幕截图保存到文件系统，而不返回上下文，自动限制为3MB。

参数:
- selector （必填）
- filePath （必填）：保存文件的绝对路径
- padding （可选）：像素填充（默认值：0）
- maxWidth （可选）：自动缩放的最大宽度（默认值：1024，原始值为空）
- maxHeight （可选）：自动缩放的最大高度（默认值：8000，原始值为空）
- quality （可选）：JPEG质量1-100（默认值：80）
- format （可选）：png、jpeg或auto（默认值：auto）
用例：基线截图、文件存储（默认质量高于 screenshot 工具）
退货：文件路径和元数据（不是图像数据）
默认行为：自动缩放和压缩以节省磁盘空间
自动压缩：如果图像超过3 MB，则会自动降低质量或缩小以适应限制

4.高级工具

executeScript

在页面上下文中使用可选的屏幕截图执行任意JavaScript。

参数:
- script （必填）：JavaScript代码
- waitAfter （可选）：等待时间（毫秒）（默认值：500）
- screenshot （可选）：捕获屏幕截图（默认值：性能为false）⚡
- timeout （可选）：最大操作时间（毫秒）（默认值：30000）
用例：复杂的交互、自定义操作
退货：执行结果+可选截图
演出：无需屏幕截图，速度提高2-10倍
顶层 return：使用顶级的任何代码段 return （例如。 return document.title, const x = 1; return x，或包含 function 在回调中）只起作用——它首先按原样运行，只有在引擎报告“非法返回语句”时才重新包装在异步IIFE中。裸露的表情，如 document.title 仍然返回其值。无手册 (() => { ... })() 需要包装。
框架：在活动帧内运行 switchFrame （参见框架工具)；默认为主框架。

getConsoleLogs

检索浏览器控制台日志（日志、警告、错误等）。

参数:
- types （可选）：要筛选的日志类型数组
- clear （可选）：读取后清除日志（默认值：false）
用例：调试JavaScript错误，跟踪行为
退货：带有时间戳的日志条目数组

网络监控（3个专用工具）

跨页面导航自动捕获。所有网络请求都会被自动监控。

listNetworkRequests

通过以下方式获取网络请求的简洁摘要 分页支持 -最小的令牌使用量。

参数:
- types （可选）：请求类型数组（默认值： ['Fetch', 'XHR'])
- status （可选）：按状态筛选（待定、已完成、失败、全部）
- limit （可选）：要返回的最大请求数（默认值：50，最大值：500）
- offset （可选）：要跳过的请求数（默认值：0）
- clear （可选）：读取后清除请求（默认值：false）
退货：对象 totalCount, returnedCount, hasMore, offset, limit，并分页 requests 数组
用例：对大型请求列表使用分页的API调用的快速概述
示例:
- listNetworkRequests() → 前50个请求
- listNetworkRequests({ limit: 20, offset: 20 }) → 请求21-40
- 答复： { totalCount: 150, returnedCount: 50, hasMore: true, offset: 0, limit: 50, requests: [...] }

getNetworkRequest

按ID获取单个请求的完整详细信息。

参数:
- requestId （必填）：来自listNetworkRequests的请求ID
退货：完整的请求/响应，包括标头、有效载荷、时间、mime类型
用例：在列表中识别出具体请求后，深入研究该请求
示例: getNetworkRequest({ requestId: "123" }) → 完整的细节，包括标题、正文、时间

filterNetworkRequests

按URL模式过滤请求，并提供完整详细信息。

参数:
- urlPattern （必填）：URL模式（正则表达式或部分匹配）
- types （可选）：请求类型数组（默认值： ['Fetch', 'XHR'])
- clear （可选）：读取后清除请求（默认值：false）
退货：匹配模式的完整请求详细信息数组
用例：获取对具有完整数据的特定终结点的所有API调用
示例: filterNetworkRequests({ urlPattern: "api/users" }) → 发送给/api/users的所有请求，并提供完整详细信息

工作流程:

listNetworkRequests() -查看所有请求（压缩）
getNetworkRequest({ requestId: "..." }) -检查特定请求
filterNetworkRequests({ urlPattern: "api/..." }) -获取所有匹配的请求及其详细信息

悬停

模拟鼠标悬停在元素上。首选：使用来自的APOM ID analyzePage 为了实现可靠的目标定位。

参数:
- id （可选）：来自analyzePage的APOM元素ID（例如。， "button_10"). 比选择器更受欢迎。
- selector （可选）：CSS选择器。当APOM ID不可用时使用。
- ⚠️ 要么 id 或 selector 必需（互斥）
用例：测试悬停效果、工具提示、下拉菜单
退货：确认文本

示例:

// PREFERRED: Using APOM ID
hover({ id: "button_10" })

// Alternative: Using CSS selector
hover({ selector: ".dropdown-trigger" })

按键

在特定元素上按键盘键（可选）。使用Puppeteer的可信键盘事件。

参数:
- id （可选）：按下前要聚焦的APOM元素ID
- selector （可选）：按下前使用CSS选择器聚焦
- key （必填）：按键-- 'Enter', 'Escape', 'Tab', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Backspace', 'Delete', 'Home', 'End', 'PageUp', 'PageDown', 'Space'
- modifiers （可选）：要按住的修饰键数组-- ['Control'], ['Shift'], ['Alt'], ['Meta']
- 两者都不 id 也不 selector 这是必要的——没有它们，就要专注于当前关注的任何事情
用例：表单提交（Enter）、关闭对话框（Escape）、焦点导航（Tab）、键盘快捷键（Ctrl+A）
退货：确认文本

示例:

// Submit form by pressing Enter on input
pressKey({ id: "input_20", key: "Enter" })

// Close modal with Escape (no element needed)
pressKey({ key: "Escape" })

// Select all text with Ctrl+A
pressKey({ id: "input_5", key: "a", modifiers: ["Control"] })

// Navigate with Tab
pressKey({ key: "Tab" })

setStyles

将内联CSS样式应用于元素以进行实时编辑。

参数:
- selector （必填）
- styles （必需）：｛name，value｝对数组
用例：测试设计变更、快速原型制作
退货：应用样式确认

setViewport

更改视口尺寸以进行响应式测试。

参数:
- width （必填）：320-4000px
- height （必填）：200-3000px
- deviceScaleFactor （可选）：0.5-3（默认值：1）
用例：测试移动设备、平板电脑、桌面布局
退货：实际视口尺寸

getViewport

获取当前视口大小和设备像素比。

参数：无
用例：检查当前屏幕尺寸
退货：视口度量（宽度、高度、DPR）

导航至

在保留浏览器实例的同时导航到不同的URL。

参数:
- url （必填）
- waitUntil （可选）：加载事件类型
用例：在工作流中的页面之间移动
退货：新页面标题。导航后网络摘要仅列出 XHR/提取 请求（静态资产——JS块、CSS、字体、图像——被隐藏和计数），并以前12个为上限 … N more 请注意，因此繁重的SPA负载不会掩盖信号。
备注：将活动帧重置为主帧（请参见框架工具).

5.选项卡管理工具

用于管理多个浏览器选项卡的工具。通过打开新选项卡 window.open(), target="_blank"，或自动检测和跟踪用户动作。

listTabs

列出所有打开的浏览器选项卡及其URL、标题和活动状态。

参数：无
退货:
- tabs：数组 { index, url, title, isActive }
- totalCount：打开的选项卡数量
- newTabsDetected （可选）：自上次检查以来打开的选项卡数组
用例：查看所有打开的选项卡，检查新打开的选项卡

// Example response
{
  "tabs": [
    { "index": 0, "url": "https://example.com", "title": "Example", "isActive": false },
    { "index": 1, "url": "https://google.com", "title": "Google", "isActive": true }
  ],
  "totalCount": 2,
  "newTabsDetected": [
    { "timestamp": "2026-01-25T...", "url": "https://google.com", "openerUrl": "https://example.com" }
  ]
}

切换标签

按索引或URL模式切换到其他浏览器选项卡。

参数:
- tab （必填）：标签索引（数字，从0开始）或URL模式（字符串，部分匹配）
用例：在多选项卡工作流的选项卡之间切换
退货: { success, switchedTo: { url, title } }

// Switch by index
switchTab({ tab: 0 })

// Switch by URL pattern
switchTab({ tab: "google.com" })

5a。框架工具（iframe自动化）

用于自动化UI位于 <iframe> --包括跨域 iframe（例如，托管在不同子域上的小部件）。无法从页面JavaScript访问跨源帧（同源策略块 iframe.contentDocument)，但ChromeTools通过CDP解决这些问题，因此SOP不适用。

默认情况下，所有工具都在 主机架.之后 switchFrame，元素工具-- click, type, hover, selectOption, pressKey, scrollTo, waitForElement, analyzePage, findElementsByText, smartFindElement, executeScript --奔跑 在所选框架内 直到你重置。活动帧会自动重置 navigateTo.

listFrames

列出当前页面上的所有帧，以便您可以发现要切换到哪个帧。

参数：无
退货: { count, activeFrame, frames: [{ url, name, isMain }], hint }
用例：查找跨源iframe（例如。 app.example.com)在切换到它之前

switchFrame

为后续图元工具设置活动框架。来电 没有争论 以重置回主帧。

参数（提供一个或不提供重置）：
- frameUrl （可选）：与每个帧的URL匹配的子字符串（例如。 "app.example.com").选择第一场比赛。
- frameSelector （可选）：CSS选择器 <iframe> 元素；其内容框架变得活跃。
退货: { active: <frame url>, matcher, frames } （或 { active: null } 重置时）
用例：输入跨源iframe以单击/填写在那里呈现的表单

// Discover frames
listFrames()
// → { count: 2, frames: [ {url:".../app", isMain:true}, {url:"https://app.example.com/...", isMain:false} ] }

// Enter the cross-origin iframe
switchFrame({ frameUrl: "app.example.com" })

// Now element tools target the iframe
analyzePage()                       // returns the iframe's APOM tree
findElementsByText({ text: "Save" }) // searches inside the iframe
click({ id: "button_3" })            // clicks inside the iframe

// Back to the main document
switchFrame()

analyzePage 还包括a frames 每当页面有多个框架时，其输出中都会显示数组，因此代理可以在没有单独框架的情况下发现iframe listFrames 电话。

6.Figma工具

设计到代码验证、文件浏览、设计系统提取和具有自动3MB压缩的比较工具。

parseFigmaUrl解析FigmaURL，自动提取fileKey和nodeId。

参数:
- url （必填）：完整的Figma URL或仅fileKey
支持的格式:
- https://www.figma.com/file/ABC123/Title?node-id=1-2
- https://www.figma.com/design/ABC123/Title?node-id=1-2
- ABC123 （仅fileKey）
用例：无需从URL中手动提取fileKey和nodeId
退货: { fileKey, nodeId } 对象

listFigmaPages浏览整个Figma文件结构：所有带有ID的页面和框架。

参数:
- figmaToken （可选）：Figma API令牌
- fileKey （必填）：Figma文件密钥或完整URL
用例: 首先使用 在请求特定节点之前发现Figma文件中的内容
退货：分层结构，包括：
- 文件元数据（名称、版本、lastModified）
- 所有带有名称和ID的页面
- 每页中的所有框架，包括名称、ID、类型、尺寸

示例输出:

{
  "fileName": "Design System",
  "pagesCount": 3,
  "pages": [
    {
      "name": "🎨 Components",
      "framesCount": 25,
      "frames": [
        { "id": "123:456", "name": "Button/Primary", "type": "FRAME" }
      ]
    }
  ]
}

searchFigmaFrames在整个Figma文件中按名称搜索帧/组件。

参数:
- figmaToken （可选）：Figma API令牌
- fileKey （必填）：Figma文件密钥或完整URL
- searchQuery （必填）：搜索文本（不区分大小写）
用例：无需手动浏览即可查找特定的框架/组件
退货：所有具有ID、名称、类型、页面、维度的匹配节点
示例：搜索“login”将返回名称中包含“login”的所有帧

getFigmaComponents从Figma文件（设计系统）中提取所有组件。

参数:
- figmaToken （可选）：Figma API令牌
- fileKey （必填）：Figma文件密钥或完整URL
用例：获取设计系统组件的完整列表
退货：所有具有名称、描述和尺寸的COMPONENT和COMPONENT_SET节点

getFigmaStyles从Figma文件中获取所有共享样式（颜色、文本、效果、网格样式）。

参数:
- figmaToken （可选）：Figma API令牌
- fileKey （必填）：Figma文件密钥或完整URL
用例：提取CSS/Tailwind生成的设计标记和共享样式
退货：分类样式：
- 填充样式（颜色）
- 文本样式（排版）
- 效果样式（阴影、模糊）
- 网格样式

getFigmaColorPalette提取带有使用统计信息的完整调色板。

参数:
- figmaToken （可选）：Figma API令牌
- fileKey （必填）：Figma文件密钥或完整URL
用例：生成CSS颜色变量，了解颜色用法
退货：所有独特的颜色：
- 十六进制和RGBA值
- 使用次数
- 使用示例（使用颜色的地方）
- 按使用频率排序

convertFigmaToCode在人工智能的帮助下将Figma设计转换为React/Tailwind代码。

参数:
- figmaToken （可选）：Figma API令牌
- fileKey （必填）：Figma文件密钥
- nodeId （必填）：帧/组件ID（格式：'123:456'或'123-456'）
- framework （可选）：“react”、“react typescript”或“html”（默认值：“response”）
- includeComments （可选）：包含代码注释（默认值：true）
用例：快速原型制作、设计到代码的工作流程、实施Figma设计
运作原理:
1. 获取设计结构（布局、颜色、排版、间距）
2. 获取2倍分辨率的渲染设计图像
3. 返回具有简化JSON结构的AI优化指令
4. AI生成与设计相匹配的干净React/Tailwind代码
退货：格式化指令提示，包含：
- 设计图像参考
- 具有布局、样式和文本属性的简化JSON结构
- 框架特定指南（React组件、TypeScript类型、Tailwind类）
- 质量要求（语义HTML、可访问性、精确间距）
最适合：UI组件、登录页面、卡片设计、导航栏

getFigmaFrame

将Figma帧导出并下载为自动压缩的PNG/JPG图像。

参数:
- figmaToken （可选）：Figma API令牌（可以使用Figma_token env var）
- fileKey （必填）：来自URL的Figma文件密钥
- nodeId （必填）：Figma框架/组件ID
- scale （可选）：导出比例0.1-4（默认值：2）
- format （可选）：png、jpg、svg（默认值：png）
用例：从Figma获取设计参考以进行比较
退货：Figma帧元数据和压缩图像
自动压缩：超过3 MB的图像会通过降低质量或缩小比例自动压缩

compareFigmaToElement

设计到代码验证的黄金标准。将Figma设计像素完美与浏览器实现进行比较。

参数:
- figmaToken （可选）：Figma API令牌（可以使用Figma_token env var）
- fileKey （必填）：Figma文件密钥
- nodeId （必填）：Figma帧ID
- selector （必填）：用于比较页面元素的CSS选择器
- figmaScale （可选）：Figma导出比例（默认值：2）
- threshold （可选）：差异阈值0-1（默认值：0.05）
用例：验证实施是否符合设计规范
退货：与SSIM评分、差异百分比和三幅图像（Figma、Page、Diff map）的比较分析
自动压缩：如果超过3 MB，所有三个图像都会自动压缩

getFigmaSpecs

从Figma中提取详细的设计规范，包括文本内容、颜色、字体、尺寸和间距。

参数:
- figmaToken （可选）：Figma API令牌
- fileKey （必填）：Figma文件密钥
- nodeId （必填）：Figma框架/组件ID
用例：获得精确的设计规范和文本内容以供实施
退货：完整的设计规范，包括：
- 文本内容：text节点（按钮、标签、标题、段落）中的所有文本
- 文本内容：text节点的直接文本
- 全文内容：具有名称和可见性的所有文本节点的数组
- text摘要：总文本节点计数、可见计数、组合文本
- 样式：颜色（填充、笔划）、排版（字体、大小、粗细）、效果（阴影、模糊）
- 维度：宽度、高度、x、y坐标
- 孩子们：递归树，从所有子元素中提取文本

7.记录器工具

基于URL的存储：场景按网站域自动组织 ~/.config/chrometools-mcp/projects/{domain}/scenarios/.

自动域检测：从录制开始的URL中提取项目ID：

https://www.google.com → google
https://dev.example.com:8080 → example-8080
http://localhost:3000 → localhost-3000
file:///test.html → local

域组织规则:

仅主域（删除子域）： mail.google.com → google
所有域都包含端口： example.com:8080 → example-8080
忽略协议： http 和 https both → 同一项目

全局场景访问：所有工具(listScenarios, searchScenarios)返回场景来自 所有项目.Agent可以通过以下方式进行筛选：

projectId：基于域的标识符（例如“google”、“localhost-3000”）
entryUrl：录制开始的URL
exitUrl：录制结束的URL

示例:

// Record scenario on google.com
enableRecorder()  // Saves to ~/.config/chrometools-mcp/projects/google/scenarios/

// List ALL scenarios from all websites
listScenarios()
// Returns: [
//   { name: "search", projectId: "google", entryUrl: "https://google.com" },
//   { name: "login", projectId: "localhost-3000", entryUrl: "http://localhost:3000" }
// ]

// Agent filters by projectId or URL
scenarios.filter(s => s.projectId === "google")
scenarios.filter(s => s.entryUrl.includes("localhost"))

// Execute scenario (searches all projects automatically)
executeScenario({ name: "login" })  // Finds scenario in any project

启用记录器

将可视记录器UI小部件注入当前页面。场景会自动保存到 ~/.config/chrometools-mcp/projects/{domain}/scenarios/ 基于网站URL。

参数：无
用例：开始直观地记录用户交互
退货：存储位置的成功状态
特征:
- 具有紧凑模式的浮动小部件（最小为50x50px）
- 视觉记录指示器（红色脉冲边框）
- 启动/暂停/停止/停止&保存/清除控件
- 实时动作列表显示
- 元数据字段（名称、描述、标签）
- 从URL自动检测基于域的项目

execute场景

按名称执行之前记录的场景。通过全局索引自动搜索所有项目。

参数:
- name （必填）：场景名称
- projectId （可选）：项目ID（域），用于在多个场景具有相同名称时消除歧义。示例： "google", "localhost-3000"
- parameters （可选）：运行时参数（例如，｛email：“user@test.com" })
- executeDependencies （可选）：在运行场景之前执行依赖关系（默认值：true）
用例：跨项目运行自动化测试场景
退货：执行结果显示成功/失败状态
特征:
- 自动依赖关系解析（默认启用）
- 跨项目依赖支持
- 秘密参数注入
- 回退选择器重试逻辑
- 名称冲突检测，并显示有用的错误消息

示例:

// Execute with dependencies (default)
executeScenario({ name: "create_post" })

// Execute without dependencies
executeScenario({ name: "create_post", executeDependencies: false })

// Disambiguate when multiple scenarios have same name
executeScenario({ name: "login", projectId: "google" })
executeScenario({ name: "login", projectId: "localhost-3000" })

名称碰撞处理: 如果不同项目中存在多个同名场景，您将收到错误：

{
  "success": false,
  "error": "Multiple scenarios named 'login' found. Please specify projectId.",
  "availableProjectIds": ["google", "localhost-3000"],
  "hint": "Use: executeScenario({ name: \"login\", projectId: \"one-of-the-above\" })"
}

聪明的

从以下位置获取包含元数据的所有可用场景 所有网站。Agent可以通过以下方式进行筛选 projectId, entryUrl，或 exitUrl.

参数：无
用例：浏览所有网站上记录的场景
退货：包含名称、描述、标签、时间戳的场景数组， projectId, entryUrl, exitUrl

示例:

// List all scenarios from all websites
const scenarios = await listScenarios()

// Agent filters by projectId
const googleScenarios = scenarios.filter(s => s.projectId === "google")

// Agent filters by URL
const localhostScenarios = scenarios.filter(s => s.entryUrl.includes("localhost"))

搜索场景

按文本或标签搜索场景 所有网站。Agent可以通过以下方式进一步过滤结果 projectId 或URL。

参数:
- text （可选）：按名称/描述搜索
- tags （可选）：要筛选的标签数组
用例：在所有网站上查找特定场景
退货：将场景与 projectId, entryUrl, exitUrl 元数据

示例:

// Search across all websites
const results = await searchScenarios({ text: "login" })

// Search by tags
const authScenarios = await searchScenarios({ tags: ["auth"] })

// Agent filters results by domain
const googleLogins = results.filter(s => s.projectId === "google")

获取场景信息

获取有关场景的详细信息。自动搜索所有项目。

参数:
- name （必填）：场景名称
- includeSecrets （可选）：包含机密值（默认值：false）
用例：检查场景操作和依赖关系
退货：完整的场景详细信息（操作、元数据、依赖关系、项目信息）

deleteScenario

删除场景及其关联的机密。搜索所有项目以查找场景。

参数:
- name （必填）：场景名称
用例：清理未使用的场景
退货：成功确认

exportScenarioAsCode将场景记录为可执行测试代码，用于创建新测试文件。自动清除不稳定的选择器（CSS模块、样式化组件、情感）。可选地生成页面对象类。返回包含代码和建议文件名的JSON-Claude code将创建该文件。将测试添加到现有的文件，使用 `appendScenarioToFile` 相反。

参数:
- scenarioName （必填）：要导出的场景名称
- language （必填）：目标框架- "playwright-typescript", "playwright-python", "selenium-python", "selenium-java"
- cleanSelectors （可选）：删除不稳定的CSS类（默认值：true）
- includeComments （可选）：包括描述性注释（默认值：true）
- generatePageObject （可选）：还为页面生成页面对象类（默认值：false）。传统-使用 pageObjectMode 相反。
- pageObjectClassName （可选）：自定义页面对象类名（如果未提供，则自动生成）
- pageObjectMode （可选）：POM集成模式：
  - "none" （默认）-无页面对象
  - "generate" -生成单独的POM文件（与 generatePageObject: true)
  - "generate-integrated" -生成POM+测试用途 POM方法（导入、实例化、调用POM方法）
  - "use-existing" -生成使用 现有的 POM文件（必需 pageObjectFile)
- pageObjectFile （可选）：现有POM文件的路径（必填） "use-existing" 模式）
用例：使用可选的页面对象集成从记录的场景中创建新的测试文件
退货：JSON格式：
- action: "create_new_file"
- suggestedFileName：建议的测试文件名
- testCode：带有导入的完整测试代码
- instruction：克劳德代码说明
- pageObject （如果生成POM）：页面对象代码和元数据
- pomIntegration （如果集成POM）： { className, mode } 信息

示例1-仅测试:

// Export scenario as new Playwright TypeScript file
exportScenarioAsCode({
  scenarioName: "checkout_flow",
  language: "playwright-typescript"
})

// Returns JSON:
{
  "action": "create_new_file",
  "suggestedFileName": "checkout_flow.spec.ts",
  "testCode": "import { test, expect } from '@playwright/test';\n\ntest('checkout_flow', async ({ page }) => {\n  await page.goto('https://example.com');\n  await page.locator('button[data-testid=\"add-to-cart\"]').click();\n  await expect(page).toHaveURL(/checkout/);\n});",
  "instruction": "Create a new test file 'checkout_flow.spec.ts' with the testCode."
}

示例2-测试+单独的页面对象 （遗留）：

exportScenarioAsCode({
  scenarioName: "login_test",
  language: "playwright-typescript",
  generatePageObject: true,
  pageObjectClassName: "LoginPage"
})

示例3-测试+集成页面对象 （推荐）：

// Generate POM and test that USES POM methods (not raw selectors)
exportScenarioAsCode({
  scenarioName: "login_test",
  language: "playwright-typescript",
  pageObjectMode: "generate-integrated",
  pageObjectClassName: "LoginPage"
})

// Returns test code using POM:
// import { LoginPage } from './LoginPage';
// test('login_test', async ({ page }) => {
//   const loginPage = new LoginPage(page);
//   await loginPage.goto();
//   await loginPage.fillUsername('admin');
//   await loginPage.clickLoginBtn();
// });

示例4-使用现有POM文件进行测试:

// Use pre-existing Page Object file
exportScenarioAsCode({
  scenarioName: "login_test",
  language: "playwright-typescript",
  pageObjectMode: "use-existing",
  pageObjectFile: "./pages/LoginPage.ts"
})
// Test will import and use methods from the existing LoginPage

选择器清洁：自动删除不稳定的模式：
- CSS模块： Button_primary__2x3yZ → 移除
- 样式化组件： sc-AbCdEf-0 → 移除
- 情感： css-1a2b3c4d → 移除
- 哈希后缀： component_a1b2c3d → 移除
- 更喜欢稳定的选择器： data-testid, role, aria-label，语义属性

append场景文件

将记录的场景作为测试代码附加到 现有的 测试文件。自动清除不稳定的选择器（CSS模块、样式化组件、情感）。可选地生成页面对象类。返回带有测试代码的JSON（不含导入）-Claude code将读取文件，附加测试，然后写回。创造新测试文件，使用 exportScenarioAsCode 相反。

参数:
- scenarioName （必填）：要导出的场景名称
- language （必填）：目标框架- "playwright-typescript", "playwright-python", "selenium-python", "selenium-java"
- targetFile （必需）：要附加到的现有测试文件的路径
- testName （可选）：覆盖测试名称（默认：来自场景名称）
- insertPosition （可选）：插入位置： 'end' （默认）， 'before', 'after'
- referenceTestName （可选）：插入“before”/“after”的参考测试名称
- cleanSelectors （可选）：删除不稳定的CSS类（默认值：true）
- includeComments （可选）：包括描述性注释（默认值：true）
- generatePageObject （可选）：还为页面生成页面对象类（默认值：false）。传统-使用 pageObjectMode 相反。
- pageObjectClassName （可选）：自定义页面对象类名（如果未提供，则自动生成）
- pageObjectMode （可选）：POM集成模式- "none", "generate", "generate-integrated", "use-existing" （详见exportScenarioAsCode）
- pageObjectFile （可选）：现有POM文件的路径（必填） "use-existing" 模式）
用例：将测试添加到现有测试文件中，而不覆盖当前测试
建筑：MCP服务器仅生成测试代码（不导入）。Claude Code读取目标文件，在指定位置附加测试，然后写回文件。这种分离确保了MCP不需要文件系统访问测试文件。
退货：JSON格式：
- action: "append_test"
- targetFile：要更新的文件路径
- testCode：仅测试代码（不含导入/标头）
- testName：要附加的测试名称
- insertPosition：在哪里插入测试
- referenceTestName：“前”/“后”定位的参考测试
- instruction：Claude Code读/附加/写的说明
- pageObject （如果 generatePageObject=true)：页面对象代码和元数据

示例1-添加到末尾:

// Append test to end of existing file
appendScenarioToFile({
  scenarioName: "new_feature_test",
  language: "playwright-typescript",
  targetFile: "./tests/features.spec.ts"
})

// Returns JSON:
{
  "action": "append_test",
  "targetFile": "./tests/features.spec.ts",
  "testCode": "test('new_feature_test', async ({ page }) => {\n  // Test implementation\n  await page.click('#submit');\n  await expect(page.locator('.result')).toBeVisible();\n});",
  "testName": "new_feature_test",
  "insertPosition": "end",
  "referenceTestName": null,
  "instruction": "Read file './tests/features.spec.ts', append the testCode at position 'end', then write the file back."
}

示例2-在特定测试之前插入:

// Insert test before specific test
appendScenarioToFile({
  scenarioName: "setup_test",
  language: "selenium-python",
  targetFile: "./tests/test_suite.py",
  insertPosition: "before",
  referenceTestName: "test_main",
  testName: "test_setup_data"
})

示例3-附加页面对象:

// Append test and generate Page Object
appendScenarioToFile({
  scenarioName: "login_test",
  language: "playwright-typescript",
  targetFile: "./tests/auth.spec.ts",
  generatePageObject: true,
  pageObjectClassName: "LoginPage"
})

// Returns JSON with both test code and Page Object:
{
  "action": "append_test",
  "targetFile": "./tests/auth.spec.ts",
  "testCode": "test('login_test', async ({ page }) => {\n  await page.fill('#username', 'user');\n  await page.fill('#password', 'pass');\n  await page.click('button[type=\"submit\"]');\n});",
  "testName": "login_test",
  "insertPosition": "end",
  "referenceTestName": null,
  "pageObject": {
    "code": "export class LoginPage { ... }",
    "className": "LoginPage",
    "suggestedFileName": "LoginPage.ts",
    "elementCount": 8
  },
  "instruction": "Read file './tests/auth.spec.ts', append the testCode at position 'end', then write the file back. Also create a Page Object file 'LoginPage.ts' with the provided pageObject.code."
}

generatePageObject从当前页面结构生成页面对象模型（POM）类。分析页面，提取交互元素，并使用智能命名和辅助方法生成特定于框架的代码。

参数:
- className （可选）：页面对象类名（如果没有提供，则从页面标题/URL自动生成）
- framework （可选）：目标框架- "playwright-typescript" （默认）， "playwright-python", "selenium-python", "selenium-java"
- includeComments （可选）：包括描述性注释（默认值：true）
- groupElements （可选）：按页面部分对元素进行分组（默认值：true）
特征:
- 智能选择器生成：优先考虑id>名称>数据testid>唯一类>CSS路径
- 智能命名：从标签、占位符、文本、属性自动生成元素名称
- 节分组：按语义部分（页眉、导航、窗体、页脚、main等）对元素进行分组
- 帮助方法：自动为常见操作生成fill（）和click（）方法
- 多框架：支持Playwright（TS/Python）和Selenium（Python/Java）
用例:
- 为测试自动化生成POM类
- 从现有页面创建可维护的测试结构
- 快速设置Bootstrap测试框架
- 提取文档的页面结构
退货：带有元数据的页面对象代码（类名、url、标题、元素计数、框架）

示例:

// 1. Navigate to page
openBrowser({ url: "https://example.com/login" })

// 2. Generate Page Object
generatePageObject({
  className: "LoginPage",
  framework: "playwright-typescript",
  includeComments: true,
  groupElements: true
})

// Returns:
{
  "success": true,
  "className": "LoginPage",
  "url": "https://example.com/login",
  "title": "Login - Example Site",
  "elementCount": 12,
  "framework": "playwright-typescript",
  "code": "import { Page, Locator } from '@playwright/test';\n\nexport class LoginPage {\n  readonly page: Page;\n  \n  /** Email input field */\n  readonly emailInput: Locator;\n  /** Password input field */\n  readonly passwordInput: Locator;\n  /** Login button */\n  readonly loginButton: Locator;\n  \n  constructor(page: Page) {\n    this.page = page;\n    this.emailInput = page.locator('#email');\n    this.passwordInput = page.locator('#password');\n    this.loginButton = page.locator('button[type=\"submit\"]');\n  }\n  \n  async goto() {\n    await this.page.goto('https://example.com/login');\n  }\n  \n  async fillEmailInput(text: string) {\n    await this.emailInput.fill(text);\n  }\n  \n  async fillPasswordInput(text: string) {\n    await this.passwordInput.fill(text);\n  }\n  \n  async clickLoginButton() {\n    await this.loginButton.click();\n  }\n}"
}

支持的框架:
- playwright-typescript：使用TypeScript的剧作家（定位器、async/await、页面对象模式）
- playwright-python：使用Python的Playwright（同步API，snake_case命名）
- selenium-python：带Python的Selenium（WebDriver、显式等待、按定位器）
- selenium-java：Selenium与Java（WebDriver，页面工厂兼容）

8.API/Swagger工具

用于加载OpenAPI/Swagger规范和生成类型化API模型的工具。

`loadSwagger`

解析OpenAPI 2.0（Swagger）或3.x规范，并返回端点、模式和身份验证的结构化摘要。

参数	类型	必填	说明
`source`	string	是	URL(`https://...`)或本地文件路径 `swagger.json` / `openapi.yaml`
`format`	`'auto'`	`'json'`	`'yaml'`

答复包括：

API标题、版本、基本URL
所有具有方法、路径、操作ID、参数、请求体、响应的端点
架构摘要（属性名称、类型、枚举）
Auth方案（承载器、API密钥、OAuth2）

// Load from URL
loadSwagger({ source: "https://petstore.swagger.io/v2/swagger.json" })

// Load from local file
loadSwagger({ source: "/path/to/openapi.yaml" })

`generateApiModels`

根据OpenAPI规范生成TypeScript接口或Python数据类/pydantic模型。

参数	类型	必填	说明
`source`	string	是	规范的URL或文件路径
`language`	`'typescript'`	`'python'`	是
`format`	`'auto'`	`'json'`	`'yaml'`
`style`	`'interface'`	`'type'`	否
`pythonStyle`	`'dataclass'`	`'pydantic'`	`'typeddict'`
`includeEnums`	boolean	否	生成枚举类型（默认值： `true`)
`schemas`	string[]	否	筛选到特定的架构名称

特征：

拓扑排序确保正确的声明顺序
枚举重复数据删除（属性枚举重用顶级枚举）
allOf → 扩展/继承， oneOf/anyOf → 联合类型
具有正向参考的循环参考检测
Swagger 2.0自动标准化为OpenAPI 3.x

// Generate TypeScript interfaces
generateApiModels({
  source: "https://petstore.swagger.io/v2/swagger.json",
  language: "typescript"
})
// Returns: { code: "export interface Pet { ... }", suggestedFileName: "pet-store-api.models.ts" }

// Generate Python pydantic models
generateApiModels({
  source: "/path/to/openapi.yaml",
  language: "python",
  pythonStyle: "pydantic"
})
// Returns: { code: "class Pet(BaseModel): ...", suggestedFileName: "pet_store_api_models.py" }

// Generate only specific schemas
generateApiModels({
  source: "https://api.example.com/openapi.json",
  language: "typescript",
  schemas: ["User", "Order"]
})

典型工作流示例

// 1. Open page
openBrowser({ url: "https://example.com/form" })

// 2. Analyze page to get element IDs
analyzePage()
// Returns: { tree: {...}, groups: {...}, meta: {...} }
// Elements: input_20 (email), input_21 (password), button_45 (submit)

// 3. Fill form using APOM IDs (preferred)
type({ id: "input_20", text: "user@example.com" })
type({ id: "input_21", text: "secret123" })

// 4. Submit using APOM ID
click({ id: "button_45" })

// 5. Verify
analyzePage({ refresh: true })  // See updated state
screenshot({ selector: ".dashboard", padding: 20 })

替代方案：使用CSS选择器（仍受支持）

type({ selector: "input[name='email']", text: "user@example.com" })
click({ selector: "button[type='submit']" })

工具使用提示

持久浏览器：

每次命令后浏览器窗口都保持打开状态
人工智能请求之间可以进行手动交互
所有工具都适用于当前打开的页面

最佳实践：

从...开始 openBrowser 建立上下文
使用 screenshot 验证视觉结果
为复杂的工作流程组合工具
工具使用CDP（Chrome DevTools协议）来提高精度

配置

基本配置（Linux、macOS、Windows）

将MCP服务器添加到MCP客户端配置文件中：

克劳德桌面 (~/.claude/mcp_config.json 或 ~/AppData/Roaming/Claude/mcp_config.json 在Windows上）：

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"]
    }
  }
}

克劳德代码 (~/.claude.json):

{
  "mcpServers": {
    "chrometools": {
      "type": "stdio",
      "command": "npx",
      "args": ["chrometools-mcp"],
      "env": {}
    }
  }
}

GUI模式与无头模式

MCP服务器运行Chrome headless: false 默认情况下，这意味着：

✅ 浏览器窗口在屏幕上可见
✅ 您可以在AI请求之间与页面进行交互
✅ 您可以实时看到自动化正在做什么

GUI模式要求：

Linux/macOS：X服务器（默认情况下通常可用）
WSL（Linux的Windows子系统）：需要X服务器设置（请参阅下面的WSL设置指南）
视窗：无需额外设置

替代方案：带虚拟显示器的无头模式（xvfb）

如果你不需要看到浏览器窗口，你可以使用xvfb（虚拟X服务器）：

{
  "mcpServers": {
    "chrometools": {
      "type": "stdio",
      "command": "xvfb-run",
      "args": ["-a", "npx", "-y", "chrometools-mcp"],
      "env": {}
    }
  }
}

这将在GUI模式下运行Chrome，但在虚拟显示器上运行（窗口不可见）。

使用ENABLED_TOOLS进行工具筛选

默认情况下，所有工具都处于启用状态。您可以使用以下选项选择性地仅启用特定的工具组 ENABLED_TOOLS 环境变量。

为什么选择过滤工具？

每个工具定义在每个请求中都会发送给AI，并消耗上下文令牌。过滤工具可以减少代币使用，提高关注度，并降低API成本：

保存令牌： 更少的工具=每个请求消耗的上下文更少
降低成本： 代币使用率降低意味着API成本降低
提高专注力： AI只看到与您的工作流程相关的工具
安全/合规性： 在需要时限制可用功能

可用工具组：

组	描述	工具（计数）
`core`	基本工具	`ping`, `openBrowser` (2)
`interaction`	用户交互和框架	`click`, `type`, `scrollTo`, `waitForElement`, `hover`, `selectOption`, `selectFromGroup`, `drag`, `scrollHorizontal`, `switchFrame`, `listFrames` (11)
`inspection`	页面检查	`getComputedCss`, `getBoxModel`, `screenshot`, `saveScreenshot` (4)
`debug`	调试与网络	`getConsoleLogs`, `listNetworkRequests`, `getNetworkRequest`, `filterNetworkRequests` (4)
`advanced`	先进的自动化和人工智能	`executeScript`, `setStyles`, `setViewport`, `getViewport`, `navigateTo`, `smartFindElement`, `analyzePage`, `findElementsByText` (8)
`recorder`	场景录制	`enableRecorder`, `executeScenario`, `listScenarios`, `searchScenarios`, `getScenarioInfo`, `deleteScenario`, `exportScenarioAsCode`, `appendScenarioToFile`, `generatePageObject` (9)
`figma`	Figma集成	`getFigmaFrame`, `compareFigmaToElement`, `getFigmaSpecs`, `parseFigmaUrl`, `listFigmaPages`, `searchFigmaFrames`, `getFigmaComponents`, `getFigmaStyles`, `getFigmaColorPalette`, `convertFigmaToCode` (10)

总计： 7组48种工具

配置：

克劳德桌面 (~/.claude/mcp_config.json):

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"],
      "env": {
        "ENABLED_TOOLS": "core,interaction,inspection"
      }
    }
  }
}

克劳德代码 (~/.claude.json):

{
  "mcpServers": {
    "chrometools": {
      "type": "stdio",
      "command": "npx",
      "args": ["chrometools-mcp"],
      "env": {
        "ENABLED_TOOLS": "core,interaction,advanced"
      }
    }
  }
}

格式：

以逗号分隔的组名列表（例如。， "core,interaction,advanced")
空间会自动修剪
如果未设置或为空，则启用所有工具（默认行为）

示例配置：

仅适用于基础自动化：

"ENABLED_TOOLS": "core,interaction,inspection"

人工智能的高级自动化：

"ENABLED_TOOLS": "core,interaction,advanced"

使用调试工具：

"ENABLED_TOOLS": "core,interaction,inspection,debug"

Figma设计验证：

"ENABLED_TOOLS": "core,figma"

全自动录音：

"ENABLED_TOOLS": "core,interaction,inspection,debug,advanced,recorder"

所有工具（默认）：

"env": {}

或省略 env 整个领域。

Figma API令牌设置

要使用Figma工具，您需要配置Figma个人访问令牌。

如何获取Figma代币：

转到您的Figma帐户设置：https://www.figma.com/settings
向下滚动到“个人访问令牌”
点击“创建新的个人访问令牌”
给它起个名字（例如“chrometools mcp”）
复制生成的令牌

将令牌添加到MCP配置：

克劳德桌面 (~/.claude/mcp_config.json 或 ~/AppData/Roaming/Claude/mcp_config.json 在Windows上）：

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["chrometools-mcp"],
      "env": {
        "FIGMA_TOKEN": "your-figma-token-here"
      }
    }
  }
}

克劳德代码 (~/.claude.json):

{
  "mcpServers": {
    "chrometools": {
      "type": "stdio",
      "command": "npx",
      "args": ["chrometools-mcp"],
      "env": {
        "FIGMA_TOKEN": "your-figma-token-here"
      }
    }
  }
}

注：或者，您可以使用以下命令在每次Figma工具调用中直接传递令牌 figmaToken 参数，但使用环境变量更方便。

浏览器连接（使用您真实登录的Chrome浏览器）

默认情况下，ChromeTools通过端口上的远程调试连接到Chrome 9222，如果没有找到，它将启动一个新的Chrome浏览器 临时配置文件 （无Cookie，无登录）。自动化一个需要您的 经过身份验证的会话 （以及要访问依赖它的跨源iframe），请通过环境变量将ChromeTools指向您自己的Chrome——所有这些都是可选的：

变量	默认值	用途
`CHROMETOOLS_BROWSER_WS_ENDPOINT`	（未设置）	直接CDP websocket URL（例如。 `ws://127.0.0.1:9222/devtools/browser/<id>`).设置后，ChromeTools会直接连接到它，跳过端口发现和启动。
`CHROMETOOLS_DEBUG_PORT`	`9222`	用于发现/连接（以及启动）的远程调试端口。
`CHROMETOOLS_USER_DATA_DIR`	`<temp>/chrome-mcp-profile`	启动新实例时使用的Chrome配置文件。指向真实（或克隆）的配置文件以重用其Cookie/登录。
`CHROMETOOLS_CHROME_PATH`	平台默认值	Chrome可执行文件的路径。

快速路径——连接到已登录的Chrome浏览器：

完全关闭Chrome（当另一个Chrome保留调试端口时，配置文件无法打开调试端口）。

在正常配置文件上通过远程调试启动它：

# Windows
chrome.exe --remote-debugging-port=9222
# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222

在该Chrome浏览器中登录目标网站。ChromeTools将 connect() 对其进行跨源iframe加载验证，以及 listTabs 查看您的真实标签。

{
  "mcpServers": {
    "chrometools": {
      "type": "stdio",
      "command": "npx",
      "args": ["chrometools-mcp"],
      "env": {
        "CHROMETOOLS_USER_DATA_DIR": "C:/Users/you/chrome-mcp-real-profile"
      }
    }
  }
}

如果没有这些变量，行为就不会改变。

WSL设置指南

如果你正在使用 Windows Linux子系统（WSL），需要特殊配置才能显示Chrome GUI窗口。

📖 请参阅完整的WSL设置指南： WSL_SETUP.md

该指南包括：

逐步安装和配置VcXsrv
WSL的MCP服务器配置（3个不同选项）
测试和故障排除程序
常见问题的解决方案
所有参考链接和资源

WSL用户快速摘要：

在Windows上安装VcXsrv(下载)
在VcXsrv设置中启用“禁用访问控制”⚠️ （关键！）
配置MCP服务器 DISPLAY=<your-windows-ip>:0 环境变量
完全重新启动MCP客户端

有关详细说明，请参阅 WSL_SETUP.md.

发展

# Install dependencies
npm install

# Run locally
npm start

# Test with MCP inspector
npx @modelcontextprotocol/inspector node index.js

特征

56+强大的工具：浏览器自动化的完整工具包（包括基于模型的交互系统）
- 核心：ping，openBrowser
- 交互：单击、键入、滚动到、选择选项、选择FromGroup、拖动、滚动水平、执行ModelAction
- 检查：getElement、getComputedCss、getBoxModel、截图、saveScreen
- 高级：executeScript、getConsoleLogs、listNetworkRequest、getNetworkRequest、filterNetworkRequests、悬停、setStyles、setViewport、getViewport、navigateTo、waitForElement
- 人工智能驱动：smartFindElement、analyzePage、getElementDetails（带子分析）、findElementsByText-记录器：启用记录器、执行场景、列表场景、搜索场景、getScenarioInfo、deleteScenarioAsCode、append ScenarioToFile、generatePageObject
- Figma:getFigmaFrame、compareFigmaToElement、getFigmaSpecs、parseFigmaUrl、listFigmaPages、searchFigmaFrames、getFigma Components、getFigmaStyles、getFigmakolorPalette、convertFigmaToCode
UI框架检测：自动检测MUI、Ant Design、Chakra UI、Bootstrap、Vuetify、语义UI- 智能下拉处理：从两个本机中提取选项 <select> 以及自定义UI框架组件- APOM（代理页面对象模型）：自动分配元素ID以实现可靠的交互- analyzePage() 返回具有唯一ID的元素（例如。， input_20, button_45)
- 使用 id 点击/键入/悬停/选择选项中的参数用于稳定定位
- 使用 getElementDetails() 获取详细的元素信息
控制台日志捕获：自动JavaScript控制台监控
网络请求监控：跟踪所有HTTP/API请求（XHR、Fetch等）
持久浏览器会话：浏览器选项卡在请求之间保持打开状态
多实例支持：通过自动发现同时运行多个MCP服务器-动态端口分配（9223-9227）
- 每20秒扫描一次Chrome扩展程序端口
- 并行AI客户端的广播模式
- 妥善处理非正常停机
自动同步活动选项卡：MCP服务器自动同步到用户当前活动的选项卡- 可视化浏览器（GUI模式）：实时查看自动化
跨平台：适用于Windows/WSL、Linux、macOS
简易安装：一个带有npx的命令
CDP集成：使用Chrome DevTools协议提高精度
AI友好：针对AI代理优化的详细描述
响应式测试：用于移动设备/平板电脑/台式机的内置视口控件

多实例支持

：最多可同时运行8台MCP服务器，无需协调即可随时连接/断开。

概述

ChromeTools MCP使用 桥梁建筑 为了获得可靠的多实例支持：

多个AI客户端 （0-8）可以随时连接/断开
无扫描延迟 --与持久网桥服务的即时连接
坚韧的 --网桥在MCP进程崩溃中幸存下来，保持状态
Chrome生命周期 --使用Chrome扩展程序启动/停止桥接

运作原理

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│ Claude Desktop  │  │ Telegram Bot    │  │ Custom Script   │
│   MCP Client    │  │   MCP Client    │  │   MCP Client    │
└────────┬────────┘  └────────┬────────┘  └────────┬────────┘
         │                    │                    │
         │    WebSocket       │    WebSocket       │    WebSocket
         │    (client)        │    (client)        │    (client)
         │                    │                    │
         └────────────────────┼────────────────────┘
                              │
                              ↓
              ┌───────────────────────────────┐
              │      Bridge Service (:9223)   │
              │   (Native Messaging Host)     │
              │                               │
              │  • Stores tabs state          │
              │  • Stores recordings          │
              │  • Broadcasts events          │
              │  • Accepts 0-8 clients        │
              └───────────────┬───────────────┘
                              │
                              │ Native Messaging (stdio)
                              │
              ┌───────────────┴───────────────┐
              │      Chrome Extension         │
              │   (Event Producer)            │
              │                               │
              │  • Tracks all tabs            │
              │  • Records user actions       │
              │  • Sends events to Bridge     │
              └───────────────┬───────────────┘
                              │
                              ↓
              ┌───────────────────────────────┐
              │        Chrome Browser         │
              └───────────────────────────────┘

安装

一次性设置 （安装本机消息桥）：

npx chrometools-mcp --install-bridge

这个：

在中创建网桥服务文件 ~/.chrometools/
在系统中注册本机消息主机（Windows注册表/Chrome配置）
加载Chrome扩展程序时，Bridge将自动启动

验证安装：

npx chrometools-mcp --check-bridge

建筑

1.桥梁服务（持久中介）

Chrome在扩展程序启动时通过本机消息启动
在端口9223上运行WebSocket服务器
存储状态：选项卡、录制、录制器状态
只要Chrome还在运行
接受0-8个同时进行的MCP客户端

2.Chrome扩展程序（事件生成器）

跟踪所有浏览器选项卡（创建、更新、关闭、激活）
记录用户操作（点击、打字、导航）
通过本机消息将所有事件发送到Bridge
不关心MCP客户端，只产生事件

3.MCP服务器（事件消费者）

作为WebSocket客户端连接到网桥
连接后立即接收完整状态
获取实时事件更新
可以随时断开/重新连接而不会丢失状态

用例

短暂的人工智能会议

# User sends message to Telegram bot
# → Claude Code starts, connects to Bridge
# → Gets current tabs state instantly
# → Performs automation
# → Claude Code exits, disconnects
# → Bridge keeps running, state preserved

# Next message: same flow, instant state access

并行工作流

# Claude Desktop: form automation
# Telegram Bot: monitoring & debugging
# Custom script: data extraction

# All connected to same Bridge
# All see same browser state
# All can control Chrome

配置

安装后不需要配置。只需使用：

npx chrometools-mcp

MCP在启动时自动连接到网桥。

CLI选项

npx chrometools-mcp --install-bridge    # Install Native Messaging Bridge
npx chrometools-mcp --uninstall-bridge  # Uninstall Bridge
npx chrometools-mcp --check-bridge      # Check if Bridge is installed
npx chrometools-mcp --help              # Show help

技术细节

组件	技术	端口
网桥服务	Node.js+WebSocket服务器	9223
扩展↔ 网桥	本机消息传递（stdio）	--
MCP↔ 网桥	WebSocket（客户端）	9223

最大客户端数： 8个同时进行的MCP连接

Connect状态： 立即发送完整状态（标签、录音、录音机状态）

扩展ID: dmehkibmncgphijnigkahhlekgajhpbl （稳定，由密钥生成）

故障排除

桥梁未连接：

# Check if Bridge is installed
npx chrometools-mcp --check-bridge

# Reinstall if needed
npx chrometools-mcp --install-bridge

# Reload extension in chrome://extensions

扩展显示“已断开连接”：

Bridge仅在Chrome扩展程序处于活动状态时运行
关闭并重新打开Chrome
检查扩展服务工作器控制台是否有错误

已知限制

Angular*ngFor与动态绑定

在使用Zone.js的Angular应用程序中，任何程序化点击（包括CDP可信事件）可以触发更改检测之间事件侦听器回调。如果 *ngFor 迭代每次返回新数组引用的getter（例如。， [options]="getOptions()")Angular在分派过程中销毁并重新创建所有子元素，导致 @HostListener('click') 在目标元素上永远不要开火。只有真正的硬件鼠标事件（物理鼠标）是免疫的——CDP事件，尽管 isTrusted: true，不通过操作系统事件队列分发。

ChromeTools 自动检测 每次单击后，它都会检查目标元素是否已从DOM中删除。如果是这样 ELEMENT DETACHED 提示与解决方法指南一起显示。

应用修复 （推荐）：添加 trackBy 到 *ngFor，或者缓存数组引用，而不是每次返回一个新的引用。

变通方案 当无法修复应用程序时--使用 executeScript 直接调用Angular组件API：

// 1. Find the component instance
executeScript({ script: `
  const comp = ng.getComponent(document.querySelector('my-component'));
  // 2. Explore available events
  Object.keys(comp).filter(k => k.includes('Event'));
` })

// 3. Emit the event directly (bypasses DOM click entirely)
executeScript({ script: `
  const comp = ng.getComponent(document.querySelector('my-component'));
  comp.selectedOptionChangeEvent.emit(comp.options.find(o => o.name === 'Delete'));
` })

建筑

操纵者 Chrome自动化
MCP服务器SDK 用于协议实施
本地消息传递桥 用于持久扩展↔ MCP通信
WebSocket 支持多客户端（网桥作为服务器，MCP作为客户端）
萨德用于模式验证
标准运输 用于MCP通信

使用说明

铬醇mcp

为什么选择ChromeTools MCP？

安装

克劳德代码（CLI）

克劳德桌面

光标

谷歌反重力

其他MCP客户端

手动安装

Chrome扩展程序设置

目录

AI优化功能

为什么这很重要

主要特点

场景记录器

特征

快速开始

可用工具

⚠️ 工具使用优先级

用于点击/交互

用于填写表格

用于读取页面状态

基于模型的交互（高级）

模态/对话支持

AI驱动的工具

smartFindElementFind使用自然语言描述而不是CSS选择器查找元素。

analyzePage获取当前页面状态和结构。返回表单（带值）、输入、按钮、带选择器的链接的完整映射。

getElementDetails通过APOM ID获取特定元素的全面详细信息。可以选择分析子元素树结构。使用时 analyzePage 输出被简化，您需要完整的元素信息或希望将分析重点放在特定部分。

findElementsByText

1.核心工具

拼

打开浏览器

2.交互工具

点击

类型

滚动到

选择选项

selectFromGroup从单选框或复选框组中按名称属性选择选项。在抽象组级别工作，而不是单独点击。

拖拽

水平滚动

3.检查工具

获取元素

getComputedCss

getBox模型

截图

保存屏幕截图

4.高级工具

executeScript

getConsoleLogs

网络监控（3个专用工具）

listNetworkRequests

getNetworkRequest

filterNetworkRequests

悬停

按键

setStyles

setViewport

getViewport

导航至

5.选项卡管理工具

listTabs

切换标签

5a。框架工具（iframe自动化）

listFrames

switchFrame

6.Figma工具

parseFigmaUrl解析FigmaURL，自动提取fileKey和nodeId。

listFigmaPages浏览整个Figma文件结构：所有带有ID的页面和框架。

searchFigmaFrames在整个Figma文件中按名称搜索帧/组件。

getFigmaComponents从Figma文件（设计系统）中提取所有组件。

getFigmaStyles从Figma文件中获取所有共享样式（颜色、文本、效果、网格样式）。

getFigmaColorPalette提取带有使用统计信息的完整调色板。

convertFigmaToCode在人工智能的帮助下将Figma设计转换为React/Tailwind代码。

getFigmaFrame

compareFigmaToElement

getFigmaSpecs

7.记录器工具

启用记录器

execute场景

getElementDetails通过APOM ID获取特定元素的全面详细信息。可以选择分析子元素树结构。使用时 `analyzePage` 输出被简化，您需要完整的元素信息或希望将分析重点放在特定部分。

`loadSwagger`

`generateApiModels`