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-chromeChrome MCP Server 是一个基于 Chrome 扩展的 Model Context ProtocolMCP服务器它把 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_requestwebRequest 与 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.1get_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.2chrome_navigate导航并控制视口导航到指定 URL底层实现在 common.ts 的NavigateTool类中逻辑相当完整参数url字符串必需要导航到的 URL当refreshtrue时可省略newWindow布尔值可选创建新窗口默认falsetabId数字可选指定已存在的标签页对该标签页导航/刷新background布尔值可选不激活标签页、不聚焦窗口默认falsewidth数字可选视口宽度像素默认1280height数字可选视口高度像素默认720示例{ url: https://example.com, newWindow: true, width: 1920, height: 1080 }从源码看该工具还具备三类「隐藏能力」刷新与历史导航refreshtrue时调用chrome.tabs.reloadurl传入字面量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 分仅同主机挑选最佳匹配标签页直接激活避免重复开标签页新窗口判定newWindowtrue或显式传入width/height时打开新窗口chrome.windows.create否则在最近聚焦窗口中新开标签页chrome.tabs.create若浏览器刚启动尚无窗口还会回退到创建新窗口。导航成功后还会触发 GIF 自动录制captureFrameOnAction为可视化回放采集帧数据。2.3chrome_close_tabs关闭标签页或窗口参数tabIds数组可选要关闭的标签页 ID 数组windowIds数组可选要关闭的窗口 ID 数组示例{ tabIds: [123, 456], windowIds: [789] }源码还支持第三种用法传入url关闭所有匹配标签页——工具会把具体 URL 转换成带通配符的 Chrome match pattern如https://example.com/*后批量关闭若两个参数都未提供则默认关闭当前激活标签页。关闭前会逐一对tabIds做存在性校验并在响应中区分closedTabIds与invalidTabIds便于 Agent 感知哪些标签页已不存在。2.4chrome_switch_tab切换激活标签页参数tabId数字必需要切换到的标签页 IDwindowId数字可选该标签页所在窗口的 ID提供时会先聚焦窗口示例{ tabId: 456, windowId: 123 }实现非常直接先按需chrome.windows.update(windowId, { focused: true })再chrome.tabs.update(tabId, { active: true })最后返回切换后标签页的最新url/windowId供后续操作引用。2.5chrome_go_back_or_forward浏览器历史导航参数direction字符串必需back或forwardtabId数字可选特定标签页 ID默认活动标签页示例{ direction: back, tabId: 123 }三、截图和视觉chrome_screenshot的高级截图支持页面截图、元素截图、全页截图并可将结果以 base64 形式直接返回给模型进行视觉理解。参数name字符串可选截图文件名selector字符串可选元素截图的 CSS 选择器tabId数字可选目标标签页默认活动标签页background布尔值可选尝试不将标签页/窗口置前进行捕获纯视口截图时走 CDPwidth数字可选宽度像素默认800height数字可选高度像素默认600storeBase64布尔值可选返回 base64 数据默认falsefullPage布尔值可选捕获整个页面默认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。storeBase64true时返回data:image/png;base64,...前缀的数据Claude 等支持视觉的模型可直接消费该图进行分析selector提供时仅截取目标元素区域。建议需要让 AI「看懂」页面时开启storeBase64需要归档文件时指定name落盘需要完整长文内容时开启fullPage。四、网络监控webRequest 与 Chrome Debugger 双方案4.1chrome_network_capture_start/chrome_network_capture_stop基于chrome.webRequestAPI 捕获网络请求实现见 network-capture-web-request.ts不含响应体开销较小。参数url字符串可选要导航并捕获的 URLmaxCaptureTime数字可选最大捕获时间毫秒默认30000inactivityTimeout数字可选无活动后停止时间毫秒默认3000includeStatic布尔值可选包含静态资源默认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.2chrome_network_debugger_start/chrome_network_debugger_stop基于 Chrome Debugger APIchrome.debugger捕获包含响应体实现见 network-capture-debugger.ts适合需要分析接口返回内容的场景。参数url字符串可选要导航并捕获的 URLchrome_network_debugger_stop无参数停止调试器捕获并返回含响应体的数据。选型建议只关心请求/状态码/耗时如验证接口是否被调用、监控 XHR 频率时用 webRequest 方案需要把响应体喂给 AI 做数据抽取、断言或分析时用 Debugger 方案。4.3chrome_network_request自定义 HTTP 请求不依赖页面环境直接从扩展侧发送 HTTP 请求。参数url字符串必需请求 URLmethod字符串可选HTTP 方法默认GETheaders对象可选请求头body字符串可选请求体示例{ url: https://api.example.com/data, method: POST, headers: { Content-Type: application/json }, body: {\key\: \value\} }可配合网络捕获做「先抓包看接口 → 再直接调接口」的 API 探索流程。五、内容分析从可访问性树到 AI 语义搜索5.1chrome_read_page构建可访问性树元素发现的入口把当前页面的可见区域构建成带稳定ref_*标识符的可访问性树实现见 read-page.ts并附带视口信息是 Agent 做元素发现与规划的主要入口。参数filter字符串可选interactive时仅包含交互元素默认包含结构性与带标签的节点tabId数字可选目标标签页默认活动标签页示例{ filter: interactive }响应包含pageContent文本形式的树、viewport视口信息以及refMapCountref 总数统计。拿到树之后把ref_*传给chrome_computer、chrome_click_element、chrome_fill_or_select等工具即可精确操作对应元素无需猜测 CSS 选择器。5.2search_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.3chrome_get_web_content提取 HTML 或文本参数format字符串可选html或text默认textselector字符串可选特定元素的 CSS 选择器tabId数字可选特定标签页 ID默认活动标签页background布尔值可选抓取时不激活标签页/不聚焦窗口默认false示例{ format: text, selector: .article-content }配合selector可以只提取文章正文区域减少发给模型的 token 量。5.4chrome_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.1chrome_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|screenshottabId数字可选目标标签页默认活动标签页background布尔值可选对部分操作避免聚焦/激活标签页尽力而为ref字符串可选来自chrome_read_page的元素 ref首选用于 click/scroll/type/key也可作为拖拽终点coordinates对象可选{ x: 100, y: 200 }用于点击/滚动或作为拖拽终点startRef字符串可选拖拽起点的元素 refstartCoordinates对象可选无startRef时left_click_drag的起点坐标scrollDirection字符串可选up|down|left|rightscrollAmount数字可选滚动刻度 1–10默认 3text字符串可选type时传原始文本key时传空格分隔的按键组合如cmda Enterduration数字可选wait的等待秒数最大 30selector字符串可选无ref时fill的目标选择器value字符串可选fill的填充值示例坐标点击 / 按键组合 / ref 填充 / hover / 拖拽{ action: left_click, coordinates: { x: 420, y: 260 } }{ action: key, text: cmda Backspace }{ action: fill, ref: ref_7, value: userexample.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.2chrome_click_element按 ref / 选择器 / 坐标点击参数ref字符串可选来自chrome_read_page的元素 ref可用时优先selector字符串可选目标元素的 CSS 选择器coordinates对象可选{ x: 120, y: 240 }视口坐标ref、selector、coordinates至少提供其一。示例{ ref: ref_42 }6.3chrome_fill_or_select填充表单或选择选项参数ref字符串可选来自chrome_read_page的元素 refselector字符串可选目标元素的 CSS 选择器value字符串必需要填充或选择的值通过ref或selector定位元素二选一。示例{ ref: ref_7, value: userexample.com }6.4chrome_keyboard模拟键盘输入与快捷键参数keys字符串必需按键组合如CtrlC、Enterselector字符串可选目标元素选择器delay数字可选按键间延迟毫秒默认0示例{ keys: CtrlA, selector: #text-input, delay: 100 }七、数据管理历史与书签7.1chrome_history带过滤器搜索历史记录参数text字符串可选在 URL/标题中搜索文本startTime字符串可选开始日期ISO 格式endTime字符串可选结束日期ISO 格式maxResults数字可选最大结果数默认100excludeCurrentTabs布尔值可选排除当前标签页默认true示例{ text: github, startTime: 2024-01-01, maxResults: 50 }7.2chrome_bookmark_search按关键词搜索书签参数query字符串可选搜索关键词maxResults数字可选最大结果数默认100folderPath字符串可选在特定文件夹内搜索示例{ query: 文档, maxResults: 20, folderPath: 工作/资源 }7.3chrome_bookmark_add添加书签支持文件夹参数url字符串可选要收藏的 URL默认当前标签页title字符串可选书签标题默认页面标题parentId字符串可选父文件夹 ID 或路径createFolder布尔值可选如果不存在则创建文件夹默认false示例{ url: https://example.com, title: 示例网站, parentId: 工作/资源, createFolder: true }parentId支持用工作/资源这种路径式写法定位多级文件夹配合createFoldertrue可以做到「目标文件夹不存在就自动创建」适合自动归档场景。7.4chrome_bookmark_delete按 ID 或 URL 删除书签参数bookmarkId字符串可选要删除的书签 IDurl字符串可选要查找并删除的 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等运行选项。十、使用建议与注意事项定位元素优先用refchrome_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/。结合源码阅读可以更准确地把握每个参数在真实浏览器环境中的行为边界。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考