Chrome MCP Server 工具 API 全解析：浏览器自动化、网络监控与 AI 语义搜索实战指南-平芜编程栈

Chrome MCP Server 工具 API 全解析：浏览器自动化、网络监控与 AI 语义搜索实战指南

【免费下载链接】mcp-chromeChrome MCP Server is a Chrome extension-based Model Context Protocol (MCP) server that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search.项目地址: https://gitcode.com/gh_mirrors/mc/mcp-chrome

Chrome MCP Server 是一个基于 Chrome 扩展的 Model Context Protocol（MCP）服务器，它把 Chrome 浏览器的窗口管理、页面交互、网络抓包、内容分析与语义搜索等能力，以标准化 MCP 工具的形式暴露给 Claude 等 AI 助手。本文以仓库官方文档 docs/TOOLS_zh.md 为骨架，逐工具讲解参数、默认值、响应结构与应用场景，并结合 app/chrome-extension/entrypoints/background/tools/browser/ 下的源码实现，说明这些工具在底层是如何调用 Chrome 扩展 API 完成任务的。读完本文，你将掌握每一个 MCP 工具的正确调用姿势，以及如何把它们串成一条完整的「导航 → 交互 → 抓包 → 分析 → 收藏」自动化流水线。

一、工具体系总览

Chrome MCP Server 的工具清单由两大部分组成（见 app/native-server/src/mcp/register-tools.ts）：

静态工具：由chrome-mcp-shared包导出的TOOL_SCHEMAS定义，即本文档详细讲解的浏览器工具；
动态工具：通过listDynamicFlowTools()从扩展侧动态拉取已发布的录制流程（Record & Replay 流程），以flow.<slug>形式动态注册为可调用工具。

当 AI 助手通过tools/call发起请求时，register-tools.ts 会将{ name, args }通过 Native Messaging 发送给 Chrome 扩展的 background 服务；扩展侧的 entrypoints/background/tools/index.ts 依据工具名在toolsMap中查找到对应执行器并调用tool.execute(args)，最终把结果包装成 MCP 标准响应返回。

工具按能力分为六大类：

分类	工具	核心能力
📊 浏览器管理	`get_windows_and_tabs`、`chrome_navigate`、`chrome_close_tabs`、`chrome_switch_tab`、`chrome_go_back_or_forward`	窗口与标签页的全生命周期管理
📸 截图和视觉	`chrome_screenshot`	页面/元素/全页截图，支持 base64 返回
🌐 网络监控	`chrome_network_capture_start/stop`、`chrome_network_debugger_start/stop`、`chrome_network_request`	webRequest 与 Debugger 两种抓包方案、自定义 HTTP 请求
🔍 内容分析	`chrome_read_page`、`search_tabs_content`、`chrome_get_web_content`、`chrome_get_interactive_elements`	可访问性树、AI 语义搜索、HTML/文本提取
🎯 交互操作	`chrome_computer`、`chrome_click_element`、`chrome_fill_or_select`、`chrome_keyboard`	统一交互入口与精细化 DOM 操作
📚 数据管理	`chrome_history`、`chrome_bookmark_search/add/delete`	浏览器历史与书签检索、管理

二、浏览器管理：窗口与标签页的完整控制

2.1`get_windows_and_tabs`：盘点当前浏览器现场

列出所有打开的窗口与标签页，便于 AI 在任务开始时先「摸清现场」。参数：无。

响应：

{ "windowCount": 2, "tabCount": 5, "windows": [ { "windowId": 123, "tabs": [ { "tabId": 456, "url": "https://example.com", "title": "示例页面", "active": true } ] } ] }

windowCount/tabCount用于快速统计规模，active标记当前激活标签页。拿到windowId/tabId后，即可把它们作为后续chrome_switch_tab、chrome_navigate等工具的定位参数。

2.2`chrome_navigate`：导航并控制视口

导航到指定 URL，底层实现在 common.ts 的NavigateTool类中，逻辑相当完整：

参数：

url（字符串，必需）：要导航到的 URL；当refresh=true时可省略
newWindow（布尔值，可选）：创建新窗口（默认：false）
tabId（数字，可选）：指定已存在的标签页，对该标签页导航/刷新
background（布尔值，可选）：不激活标签页、不聚焦窗口（默认：false）
width（数字，可选）：视口宽度（像素，默认：1280）
height（数字，可选）：视口高度（像素，默认：720）

示例：

{ "url": "https://example.com", "newWindow": true, "width": 1920, "height": 1080 }

从源码看，该工具还具备三类「隐藏能力」：

刷新与历史导航：refresh=true时调用chrome.tabs.reload；url传入字面量"back"或"forward"时，会走chrome.tabs.goBack/chrome.tabs.goForward做历史跳转，可视为chrome_go_back_or_forward的另一条等价路径；
URL 去重激活：通过buildUrlPatterns()生成带www/不带www、http/https多套匹配模式，用chrome.tabs.query查找是否已有同站标签页打开，并用路径/查询串相似度打分（3 分=路径与查询完全一致，2 分=路径一致但目标无查询，1 分=仅同主机）挑选最佳匹配标签页直接激活，避免重复开标签页；
新窗口判定：newWindow=true或显式传入width/height时打开新窗口（chrome.windows.create），否则在最近聚焦窗口中新开标签页（chrome.tabs.create）；若浏览器刚启动尚无窗口，还会回退到创建新窗口。

导航成功后还会触发 GIF 自动录制（captureFrameOnAction），为可视化回放采集帧数据。

2.3`chrome_close_tabs`：关闭标签页或窗口

参数：

tabIds（数组，可选）：要关闭的标签页 ID 数组
windowIds（数组，可选）：要关闭的窗口 ID 数组

示例：

{ "tabIds": [123, 456], "windowIds": [789] }

源码还支持第三种用法：传入url关闭所有匹配标签页——工具会把具体 URL 转换成带通配符的 Chrome match pattern（如https://example.com/*）后批量关闭；若两个参数都未提供，则默认关闭当前激活标签页。关闭前会逐一对tabIds做存在性校验，并在响应中区分closedTabIds与invalidTabIds，便于 Agent 感知哪些标签页已不存在。

2.4`chrome_switch_tab`：切换激活标签页

参数：

tabId（数字，必需）：要切换到的标签页 ID
windowId（数字，可选）：该标签页所在窗口的 ID（提供时会先聚焦窗口）

示例：

{ "tabId": 456, "windowId": 123 }

实现非常直接：先按需chrome.windows.update(windowId, { focused: true })，再chrome.tabs.update(tabId, { active: true })，最后返回切换后标签页的最新url/windowId供后续操作引用。

2.5`chrome_go_back_or_forward`：浏览器历史导航

参数：

direction（字符串，必需）："back"或"forward"
tabId（数字，可选）：特定标签页 ID（默认：活动标签页）

示例：

{ "direction": "back", "tabId": 123 }

三、截图和视觉：`chrome_screenshot`的高级截图

支持页面截图、元素截图、全页截图，并可将结果以 base64 形式直接返回给模型进行视觉理解。

参数：

name（字符串，可选）：截图文件名
selector（字符串，可选）：元素截图的 CSS 选择器
tabId（数字，可选）：目标标签页（默认：活动标签页）
background（布尔值，可选）：尝试不将标签页/窗口置前进行捕获（纯视口截图时走 CDP）
width（数字，可选）：宽度（像素，默认：800）
height（数字，可选）：高度（像素，默认：600）
storeBase64（布尔值，可选）：返回 base64 数据（默认：false）
fullPage（布尔值，可选）：捕获整个页面（默认：true）

示例：

{ "selector": ".main-content", "fullPage": true, "storeBase64": true, "width": 1920, "height": 1080 }

响应：

{ "success": true, "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "dimensions": { "width": 1920, "height": 1080 } }

实现位于 screenshot.ts。storeBase64=true时返回data:image/png;base64,...前缀的数据，Claude 等支持视觉的模型可直接消费该图进行分析；selector提供时仅截取目标元素区域。建议：需要让 AI「看懂」页面时开启storeBase64，需要归档文件时指定name落盘，需要完整长文内容时开启fullPage。

四、网络监控：webRequest 与 Chrome Debugger 双方案

4.1`chrome_network_capture_start`/`chrome_network_capture_stop`

基于chrome.webRequestAPI 捕获网络请求（实现见 network-capture-web-request.ts），不含响应体，开销较小。

参数：

url（字符串，可选）：要导航并捕获的 URL
maxCaptureTime（数字，可选）：最大捕获时间（毫秒，默认：30000）
inactivityTimeout（数字，可选）：无活动后停止时间（毫秒，默认：3000）
includeStatic（布尔值，可选）：包含静态资源（默认：false）

示例：

{ "url": "https://api.example.com", "maxCaptureTime": 60000, "includeStatic": false }

chrome_network_capture_stop无参数，停止捕获并返回收集的数据：

{ "success": true, "capturedRequests": [ { "url": "https://api.example.com/data", "method": "GET", "status": 200, "requestHeaders": {...}, "responseHeaders": {...}, "responseTime": 150 } ], "summary": { "totalRequests": 15, "captureTime": 5000 } }

maxCaptureTime决定最长抓多久，inactivityTimeout用于在页面静止后提前收网，两者配合可在不浪费等待时间的前提下保证关键请求不遗漏。

4.2`chrome_network_debugger_start`/`chrome_network_debugger_stop`

基于 Chrome Debugger API（chrome.debugger）捕获，包含响应体（实现见 network-capture-debugger.ts），适合需要分析接口返回内容的场景。

参数：

url（字符串，可选）：要导航并捕获的 URL

chrome_network_debugger_stop无参数，停止调试器捕获并返回含响应体的数据。

选型建议：只关心请求/状态码/耗时（如验证接口是否被调用、监控 XHR 频率）时用 webRequest 方案；需要把响应体喂给 AI 做数据抽取、断言或分析时，用 Debugger 方案。

4.3`chrome_network_request`：自定义 HTTP 请求

不依赖页面环境，直接从扩展侧发送 HTTP 请求。

参数：

url（字符串，必需）：请求 URL
method（字符串，可选）：HTTP 方法（默认："GET"）
headers（对象，可选）：请求头
body（字符串，可选）：请求体

示例：

{ "url": "https://api.example.com/data", "method": "POST", "headers": { "Content-Type": "application/json" }, "body": "{\"key\": \"value\"}" }

可配合网络捕获做「先抓包看接口 → 再直接调接口」的 API 探索流程。

五、内容分析：从可访问性树到 AI 语义搜索

5.1`chrome_read_page`：构建可访问性树（元素发现的入口）

把当前页面的可见区域构建成带稳定ref_*标识符的可访问性树（实现见 read-page.ts），并附带视口信息，是 Agent 做元素发现与规划的主要入口。

参数：

filter（字符串，可选）：interactive时仅包含交互元素；默认包含结构性与带标签的节点
tabId（数字，可选）：目标标签页（默认：活动标签页）

示例：

{ "filter": "interactive" }

响应：包含pageContent（文本形式的树）、viewport（视口信息）以及refMapCount（ref 总数统计）。拿到树之后，把ref_*传给chrome_computer、chrome_click_element、chrome_fill_or_select等工具即可精确操作对应元素，无需猜测 CSS 选择器。

5.2`search_tabs_content`：跨标签页 AI 语义搜索

对浏览器所有标签页内容做向量化索引与语义检索（实现见 vector-search.ts）。索引数据落地在 IndexedDB，向量引擎由仓库的 WASM/SIMD 模块（app/chrome-extension/workers/）提供，可在本地完成语义计算。

参数：

query（字符串，必需）：搜索查询

示例：

{ "query": "机器学习教程" }

响应：

{ "success": true, "totalTabsSearched": 10, "matchedTabsCount": 3, "vectorSearchEnabled": true, "indexStats": { "totalDocuments": 150, "totalTabs": 10, "semanticEngineReady": true }, "matchedTabs": [ { "tabId": 123, "url": "https://example.com/ml-tutorial", "title": "机器学习教程", "semanticScore": 0.85, "matchedSnippets": ["机器学习简介..."], "chunkSource": "content" } ] }

关键字段说明：

totalTabsSearched/matchedTabsCount：参与搜索的标签页数与命中数；
vectorSearchEnabled/indexStats.semanticEngineReady：向量检索是否可用、语义引擎是否就绪（模型资源尚未就绪时会降级为关键词检索）；
semanticScore：语义相似度分数（0~1，越高越相关），matchedSnippets是命中的文本片段，chunkSource标明片段来源。

这是本仓库最有特色的能力：AI 可以在不打开标签页的情况下，用自然语言在整个浏览器会话里「回忆」和「定位」曾经看过的重要内容。

5.3`chrome_get_web_content`：提取 HTML 或文本

参数：

format（字符串，可选）："html"或"text"（默认："text"）
selector（字符串，可选）：特定元素的 CSS 选择器
tabId（数字，可选）：特定标签页 ID（默认：活动标签页）
background（布尔值，可选）：抓取时不激活标签页/不聚焦窗口（默认：false）

示例：

{ "format": "text", "selector": ".article-content" }

配合selector可以只提取文章正文区域，减少发给模型的 token 量。

5.4`chrome_get_interactive_elements`（已弃用）

早期用于查找页面上可点击/可交互元素：

参数：tabId（数字，可选，默认：活动标签页）

响应：

{ "elements": [ { "selector": "#submit-button", "type": "button", "text": "提交", "visible": true, "clickable": true } ] }

该工具已被chrome_read_page取代（read_page实现会在可访问性树不可用或过于稀疏时自动回退到 interactive-elements 逻辑）。它已不再出现在ListTools的返回清单中，仅保留用于向后兼容。

六、交互操作：从统一入口到精细化 DOM 操作

6.1`chrome_computer`：统一高级交互工具

优先使用高层 DOM 动作、在必要时回退到 CDP 的「一站式」交互工具（实现见 computer.ts），支持 hover、点击、拖拽、滚动、输入、按键组合、填充、等待与截图。如果此前通过chrome_screenshot截过图，传入的坐标会自动从截图坐标系缩放到视口坐标系，这让「截图 → 看图 → 点坐标」的视觉闭环变得非常可靠。

参数：

action（字符串，必需）：left_click|right_click|double_click|triple_click|left_click_drag|scroll|type|key|fill|hover|wait|screenshot
tabId（数字，可选）：目标标签页（默认：活动标签页）
background（布尔值，可选）：对部分操作避免聚焦/激活标签页（尽力而为）
ref（字符串，可选）：来自chrome_read_page的元素 ref（首选），用于 click/scroll/type/key，也可作为拖拽终点
coordinates（对象，可选）：{ "x": 100, "y": 200 }，用于点击/滚动或作为拖拽终点
startRef（字符串，可选）：拖拽起点的元素 ref
startCoordinates（对象，可选）：无startRef时left_click_drag的起点坐标
scrollDirection（字符串，可选）：up|down|left|right
scrollAmount（数字，可选）：滚动刻度 1–10（默认 3）
text（字符串，可选）：type时传原始文本；key时传空格分隔的按键组合（如"cmd+a Enter"）
duration（数字，可选）：wait的等待秒数（最大 30）
selector（字符串，可选）：无ref时fill的目标选择器
value（字符串，可选）：fill的填充值

示例（坐标点击 / 按键组合 / ref 填充 / hover / 拖拽）：

{ "action": "left_click", "coordinates": { "x": 420, "y": 260 } }

{ "action": "key", "text": "cmd+a Backspace" }

{ "action": "fill", "ref": "ref_7", "value": "user@example.com" }

{ "action": "hover", "ref": "ref_12", "duration": 0.6 }

{ "action": "left_click_drag", "startRef": "ref_10", "ref": "ref_15" }

最佳实践：优先用ref定位元素（对布局变化鲁棒），截图场景用coordinates（直观、适配视觉模型），left_click_drag同时提供startRef/ref或startCoordinates/coordinates两组组合。

6.2`chrome_click_element`：按 ref / 选择器 / 坐标点击

参数：

ref（字符串，可选）：来自chrome_read_page的元素 ref（可用时优先）
selector（字符串，可选）：目标元素的 CSS 选择器
coordinates（对象，可选）：{ "x": 120, "y": 240 }视口坐标

ref、selector、coordinates至少提供其一。

示例：

{ "ref": "ref_42" }

6.3`chrome_fill_or_select`：填充表单或选择选项

参数：

ref（字符串，可选）：来自chrome_read_page的元素 ref
selector（字符串，可选）：目标元素的 CSS 选择器
value（字符串，必需）：要填充或选择的值

通过ref或selector定位元素（二选一）。

示例：

{ "ref": "ref_7", "value": "user@example.com" }

6.4`chrome_keyboard`：模拟键盘输入与快捷键

参数：

keys（字符串，必需）：按键组合（如"Ctrl+C"、"Enter"）
selector（字符串，可选）：目标元素选择器
delay（数字，可选）：按键间延迟（毫秒，默认：0）

示例：

{ "keys": "Ctrl+A", "selector": "#text-input", "delay": 100 }

七、数据管理：历史与书签

7.1`chrome_history`：带过滤器搜索历史记录

参数：

text（字符串，可选）：在 URL/标题中搜索文本
startTime（字符串，可选）：开始日期（ISO 格式）
endTime（字符串，可选）：结束日期（ISO 格式）
maxResults（数字，可选）：最大结果数（默认：100）
excludeCurrentTabs（布尔值，可选）：排除当前标签页（默认：true）

示例：

{ "text": "github", "startTime": "2024-01-01", "maxResults": 50 }

7.2`chrome_bookmark_search`：按关键词搜索书签

参数：

query（字符串，可选）：搜索关键词
maxResults（数字，可选）：最大结果数（默认：100）
folderPath（字符串，可选）：在特定文件夹内搜索

示例：

{ "query": "文档", "maxResults": 20, "folderPath": "工作/资源" }

7.3`chrome_bookmark_add`：添加书签（支持文件夹）

参数：

url（字符串，可选）：要收藏的 URL（默认：当前标签页）
title（字符串，可选）：书签标题（默认：页面标题）
parentId（字符串，可选）：父文件夹 ID 或路径
createFolder（布尔值，可选）：如果不存在则创建文件夹（默认：false）

示例：

{ "url": "https://example.com", "title": "示例网站", "parentId": "工作/资源", "createFolder": true }

parentId支持用工作/资源这种路径式写法定位多级文件夹，配合createFolder=true可以做到「目标文件夹不存在就自动创建」，适合自动归档场景。

7.4`chrome_bookmark_delete`：按 ID 或 URL 删除书签

参数：

bookmarkId（字符串，可选）：要删除的书签 ID
url（字符串，可选）：要查找并删除的 URL

示例：

{ "url": "https://example.com" }

八、统一响应格式

所有工具都返回 MCP 标准的CallToolResult结构：

{ "content": [ { "type": "text", "text": "包含实际响应数据的 JSON 字符串" } ], "isError": false }

出错时：

{ "content": [ { "type": "text", "text": "描述出错原因的错误消息" } ], "isError": true }

实际数据始终是content[0].text里的 JSON 字符串（多数工具内部用JSON.stringify包装）。AI 侧应：先看isError判断成败，再解析text里的 JSON 取业务字段。工具执行层的错误兜底见 common/tool-handler.ts 的createErrorResponse与 entrypoints/background/tools/index.ts 的异常捕获逻辑；Native Server 侧的超时上限为 120 秒（register-tools.ts），耗时操作（如性能分析、长流程录制）不会被过早掐断。

九、完整工作流示例

把上述工具串成一条「调研一条数据」的端到端流水线：

// 1. 导航到页面 await callTool('chrome_navigate', { url: 'https://example.com', }); // 2. 截图 const screenshot = await callTool('chrome_screenshot', { fullPage: true, storeBase64: true, }); // 3. 开始网络监控 await callTool('chrome_network_capture_start', { maxCaptureTime: 30000, }); // 4. 与页面交互 await callTool('chrome_click_element', { selector: '#load-data-button', }); // 5. 语义搜索内容 const searchResults = await callTool('search_tabs_content', { query: '用户数据分析', }); // 6. 停止网络捕获 const networkData = await callTool('chrome_network_capture_stop'); // 7. 保存书签 await callTool('chrome_bookmark_add', { title: '数据分析页面', parentId: '工作/分析', });

流程解读：

第 1~2 步：导航 + 全页截图，让 AI「看到」页面；
第 3、6 步：在交互前后开启/关闭抓包，收集页面加载的 API 请求；
第 4 步：点击按钮触发数据加载（此时请求已被捕获）；
第 5 步：在整个浏览器标签页里语义检索相关知识点，为分析提供上下文；
第 7 步：把有价值的页面归档到指定书签目录。

更复杂的自动化（多步骤录制、条件分支、变量回填）可由动态流程工具flow.<slug>承接——它由 register-tools.ts 依据已发布录制流程动态生成参数 Schema，将流程变量映射为工具入参，并支持tabTarget、refresh、captureNetwork、timeoutMs等运行选项。

十、使用建议与注意事项

定位元素优先用ref：chrome_read_page返回的ref_*标识稳定，比 CSS 选择器对页面结构变化更鲁棒；选择器定位适合「结构已知且简单」的场景。
截图驱动视觉交互：chrome_screenshot配合storeBase64返回图像给多模态模型，chrome_computer会自动把截图坐标换算为视口坐标，形成「看 → 想 → 点」闭环。
网络监控按需选择：仅需要请求元数据用chrome_network_capture_start，需要响应体分析用chrome_network_debugger_start；设置合理的maxCaptureTime/inactivityTimeout避免长期空转。
语义搜索注意引擎就绪状态：semanticEngineReady/vectorSearchEnabled为false时检索可能退化为关键词匹配，语义相关性会下降，可先检查indexStats再决定是否依赖其结论。
区分isError与业务字段：MCP 层错误看isError，业务结果解析content[0].text；部分工具（如chrome_close_tabs找不到标签页）返回success: false但isError: false，需要按业务字段判断。

这份 API 参考的完整源码与配套文档还包括：英文版 docs/TOOLS.md、架构说明 docs/ARCHITECTURE_zh.md、故障排查 docs/TROUBLESHOOTING_zh.md，以及全部工具实现 app/chrome-extension/entrypoints/background/tools/browser/。结合源码阅读，可以更准确地把握每个参数在真实浏览器环境中的行为边界。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Chrome MCP Server 工具 API 全解析：浏览器自动化、网络监控与 AI 语义搜索实战指南