MCP Browser

✅ MCPBrowser（MCP Browser）

⚠️ 安全提示： MCPBrowser 会提取网页内容并提供给你的 AI Agent（例如 GitHub Copilot、Claude、Kiro、Antigravity），随后由 Agent 将内容发送给所用的大模型提供商（例如 Anthropic、OpenAI、GitHub）进行处理。请确保你信任 Agent 和大模型提供商，尤其是在访问包含敏感或私人数据的页面时。MCPBrowser 结合了私人数据访问、不可信内容暴露和外部通信（MCP 的“致命三要素”）——所有工具注释都会准确声明这些风险，以便 MCP 客户端实施适当的安全控制。详情请参阅 MCP_COMPLIANCE.md。

💡 为什么选择 MCPBrowser，而不是 Puppeteer/Playwright MCP 服务？ Puppeteer 和 Playwright 是浏览器自动化库——它们的 MCP 服务会向 Agent 提供原始的底层浏览器命令。MCPBrowser 使用 Puppeteer 作为底层技术，专为 AI Agent 打造，并加入智能层来自动处理复杂环节。

Agent 可获得简洁的 HTML（体积缩小 90%）、自动检测 SPA（React、Vue、Angular）、处理身份验证流程（SSO、重定向、多步登录）、发现表单并填写多个字段、获取包含后续步骤指导的结构化响应、按域名重复使用标签页，以及无需重新加载页面即可立即重新提取 DOM。每次 MCPBrowser 工具调用都可替代 5-8 次原始浏览器自动化调用——在 MCPBrowser 中只需 4 步的典型工作流，用 Puppeteer/Playwright MCP 则需要 20 多次调用，从而节省令牌并显著提升 Agent 的速度。查看下方的完整对比。

MCPBrowser 是一款 MCP 浏览器服务，让 AI 助手能够使用真实的 Chrome、Edge 或 Brave 浏览器浏览网页。 这款基于浏览器的 MCP 服务可以获取任意网页的内容，尤其适用于受身份验证、CAPTCHA、反机器人保护，或需要 JavaScript 渲染的网页。它使用你的真实浏览器进行网页自动化，因此你可以像平常一样登录，然后自动提取内容。支持企业 SSO、登录表单、Cloudflare，以及大量使用 JavaScript 的网站（SPA、仪表板）。

这是一个使用 stdio transport 的 MCP（Model Context Protocol） 服务。当标准 HTTP 请求失败时，你的 AI 助手会使用此网页浏览器 MCP 服务访问需要身份验证、受 CAPTCHA 保护或大量使用 JavaScript（SPA）的页面。连接后，浏览器 MCP 服务可以浏览网站、与页面元素交互，并将 HTML 发回 AI 助手。这样一来，你的 AI 就能像你一样浏览网页。

AI 助手使用 MCPBrowser 的工作流示例

1. browser_fetch_webpage    → Load the login page
2. browser_type_text        → Enter username and password (multiple fields at once)
3. browser_click_element    → Click "Sign In"
4. browser_get_current_html → Extract the content after login

为什么选择 MCPBrowser，而不是 Puppeteer/Playwright MCP 服务？

Puppeteer 和 Playwright 是浏览器自动化库——它们的 MCP 服务会暴露底层浏览器命令，Agent 必须自行处理 SPA、身份验证流程、混乱的 HTML 和各种边缘情况。**MCPBrowser 专为 AI Agent 打造。**它在底层使用 Puppeteer，并添加了智能层，让 Agent 能专注于任务，而不是与浏览器周旋。

	MCPBrowser	Puppeteer/Playwright MCP
HTML 输出	清洁、针对大模型优化（体积约小 90%）——剔除脚本、样式、SVG、跟踪属性，并转换相对 URL	原始 DOM
SPA 支持	自动检测 React、Vue、Angular、Svelte、Next.js、Nuxt——采用适配框架的等待策略	Agent 必须手动配置等待
身份验证	检测登录页面、SSO 重定向、多步骤身份验证——跟踪重定向链，并采用两阶段超时（SSO 为 5s → 手动操作为 20min）	Agent 必须为每个身份验证步骤编写脚本
表单交互	browser_detect_forms 可发现所有字段、标签和约束；browser_type_text 可一次填写多个字段	一次填写一个字段，手动指定选择器
响应格式	类型化、结构化，并提供 nextSteps 指引——区分软失败与硬失败，并提供恢复操作	原始结果、通用错误
标签页管理	按域名池化——复用标签页，并在浏览器重新连接后继续使用	每次请求创建新上下文
DOM 重新提取	browser_get_current_html——即时提取，无需重新加载（快 10-50 倍）	必须重新获取完整页面
插件系统	根据 URL/DOM 模式检测已知网站，提供网站专属操作并进行置信度评分	不适用
专为	AI Agent	浏览器测试自动化
Agent 效率	1 次工具调用可替代 5-8 次原始浏览器调用——4 步登录流程只需调用 4 次，而非 20 多次，从而节省令牌并减少往返次数	每个步骤（导航、等待、查询、输入、点击）都需要单独调用

目录

• MCPBrowser 相较于 Puppeteer/Playwright MCP 服务有何优势？
• 要求
• 安装
  • VS Code 扩展
  • Claude Code
  • Claude Desktop
  • npm Package
• MCP 工具
  • browser_fetch_webpage
  • browser_execute_javascript
  • browser_click_element
  • browser_type_text
  • browser_get_current_html
  • browser_scroll_page
  • browser_take_screenshot
  • browser_close_tab
• Microsoft Word Online 插件
• 开发操作
• CLI 模式
• 配置（可选）
• 故障排除
• 链接

要求

• Chrome、Edge 或 Brave 浏览器
• Node.js 18+（包含 npm）

**注意：**系统必须安装 Node.js。VS Code 扩展和 npm Package 都需要 Node.js 才能运行 MCP 服务。如果尚未安装，请从 nodejs.org 下载。

安装

#	平台	难度
1	VS Code 扩展	一键安装
2	Claude Code	一条命令
3	OpenClaw	一条命令
4	Claude Desktop	手动
5	npm Package	手动

选项 1：VS Code 扩展

从 VS Code Marketplace 或 Open VSX Registry 安装，或运行：

code --install-extension cherchyk.mcpbrowser

该扩展会自动为你的 AI Agent（GitHub Copilot、Kiro Agent、Antigravity Agent）安装并配置所有内容。也适用于 VSCodium 和其他兼容 Open VSX 的编辑器。

选项 2：Claude Code

claude mcp add mcpbrowser --scope user -- npx -y mcpbrowser@latest

验证是否正常运行：

claude mcp list

你应该会看到：

mcpbrowser: npx -y mcpbrowser@latest - ✓ Connected

就这么简单！让 Claude 获取任意受保护页面：

“使用 mcpbrowser 获取 https://portal.azure.com”

选项 3：OpenClaw

OpenClaw 是一款可在你的设备上运行的个人 AI 助手。添加 MCPBrowser，即可为其提供浏览器自动化功能：

openclaw mcp add mcpbrowser -- npx -y mcpbrowser@latest

验证是否正常运行：

openclaw mcp list

现在，OpenClaw 可以使用你现有的浏览器会话浏览已验证身份的页面、填写表单并与 Web 应用交互。

选项 4：Claude Desktop

将以下内容添加到你的配置文件中（如果文件不存在，请创建）：

Windows： %APPDATA%\Claude\claude_desktop_config.json（例如，C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json）
Mac： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "MCPBrowser": {
      "command": "npx",
      "args": ["-y", "mcpbrowser@latest"]
    }
  }
}

保存后重启 Claude Desktop。

选项 5：npm Package

适用于 VS Code、Kiro、Antigravity 或其他编辑器——手动配置 MCP。将以下内容添加到你的 mcp.json：

Windows： %APPDATA%\Code\User\mcp.json Mac/Linux： ~/.config/Code/User/mcp.json

{
  "servers": {
    "MCPBrowser": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcpbrowser@latest"]
    }
  }
}

MCP 工具

browser_fetch_webpage

使用你的 Chrome/Edge/Brave 浏览器抓取网页。可处理身份验证、CAPTCHA、SSO、反机器人保护和大量使用 JavaScript 的网站。会在浏览器标签页中打开 URL（同一域名会复用现有标签页），并等待页面完全加载后再返回内容。自动检测 SPA（React、Vue、Angular），并等待 JavaScript 渲染内容。

参数：

• url（string，必填）- 要抓取的 URL
• removeUnnecessaryHTML（boolean，可选，默认值：true）- 删除不必要的 HTML，体积最多可减少约 90%
• postLoadWait（number，可选，默认值：0）- 页面加载后、提取 HTML 前额外等待的毫秒数。适用于需要更多时间渲染的页面。

示例：

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

// Fetch with extra wait time for slow-rendering pages
{ url: "https://dashboard.example.com", postLoadWait: 2000 }

// Keep full HTML without cleanup
{ url: "https://example.com", removeUnnecessaryHTML: false }

---

browser_execute_javascript

在当前页面上下文中执行 JavaScript 代码片段，并返回结果及元数据（执行时间、截断标记、URL 变更标记）。可用于结构化提取（例如收件箱行），或执行通过协议点击不可靠的 JavaScript 驱动型 UI 操作。

⚠️ 注意： 必须先通过 browser_fetch_webpage 加载页面。

参数：

• url（string，必填）- 页面 URL（必须与先前抓取的页面匹配）
• script（string，必填）- 要在页面上下文中执行的 JavaScript 源代码
• timeoutMs（number，可选，默认值：30000，最大值：60000）- 执行超时时间
• returnType（string，可选，默认值：json）- json | text | void

返回： 序列化结果（DOM 节点返回 outerHTML）、type、executionTimeMs、truncated、urlChanged、currentUrl，以及脚本抛出错误或超时时的结构化 error。

示例：

{
  "action": "browser_execute_javascript",
  "url": "https://mail.google.com/",
  "script": "[...document.querySelectorAll('tr.zA')].slice(0,5).map((row,i)=>({index:i+1,sender:row.querySelector('.zF,.yP')?.textContent,subject:row.querySelector('.bog')?.textContent}))",
  "timeoutMs": 30000,
  "returnType": "json"
}

---

browser_click_element

点击任意可点击元素（按钮、链接、带有 onclick 处理程序的 div 等）。可通过 CSS 选择器或可见文本内容定位目标。会自动将元素滚动至视野内，并在点击后等待页面稳定。

⚠️ 注意： 必须先通过 browser_fetch_webpage 加载页面。

参数：

• url（string，必填）- 页面 URL（必须与先前抓取的页面匹配）
• selector（string，可选）- 元素的 CSS 选择器（例如 #submit-btn、.login-button）
• text（string，可选）- 未提供选择器时用于搜索的文本内容（例如“登录”“提交”）
• returnHtml（boolean，可选，默认值：true）- 是否等待页面稳定并在点击后返回 HTML。对于快速表单交互（复选框、单选按钮），可设为 false
• removeUnnecessaryHTML（boolean，可选，默认值：true）- 删除不必要的 HTML 以缩减体积。仅在 returnHtml 为 true 时使用
• postClickWait（number，可选，默认值：1000）- 点击后等待 SPA 渲染动态内容的毫秒数
• waitForElementTimeout（number，可选，默认值：1000）- 等待元素的最长时间，单位为毫秒

示例：

// Click by text content
{ url: "https://example.com", text: "Sign In" }

// Click by CSS selector
{ url: "https://example.com", selector: "#login-button" }

// Click without waiting for HTML (fast checkbox toggle)
{ url: "https://example.com", selector: "#agree-checkbox", returnHtml: false }

// Click with custom wait time
{ url: "https://example.com", text: "Load More", postClickWait: 2000 }

回退行为： 如果找到元素后原生点击超时，MCPBrowser 会自动改用基于 JavaScript 的点击方式重试，并返回 fallbackUsed、nativeAttempt 和 fallbackAttempt 元数据。如果两次尝试都失败，响应会列出两种错误，供你选择其他策略。

---

browser_type_text

在一次调用中向一个或多个输入字段输入文本。支持一次性填写整个表单，实现高效自动化。默认会自动清除现有文本。

**⚠️ 注意：**必须先通过 browser_fetch_webpage 加载页面。

参数：

• url（字符串，必填）- 页面 URL（必须与先前抓取的页面匹配）
• fields（数组，必填）- 要填写的字段数组。每个字段对象包含：
  • selector（字符串，必填）- 输入元素的 CSS 选择器（例如：#username、input[name="email"]）
  • text（字符串，必填）- 要输入到字段中的文本
  • clear（布尔值，可选，默认值：true）- 是否先清除现有文本
  • waitForElementTimeout（数字，可选，默认值：5000）- 等待元素的最长时间，单位为毫秒
• returnHtml（布尔值，可选，默认值：true）- 是否等待页面稳定并在输入后返回 HTML
• removeUnnecessaryHTML（布尔值，可选，默认值：true）- 是否移除不必要的 HTML 以减小体积。仅当 returnHtml 为 true 时使用
• postTypeWait（数字，可选，默认值：1000）- 输入后等待的毫秒数，以便 SPA 渲染动态内容

示例：

// Fill multiple fields at once (login form)
{
  url: "https://example.com/login",
  fields: [
    { selector: "#username", text: "[email protected]" },
    { selector: "#password", text: "secretpass123" }
  ]
}

// Single field input
{ url: "https://example.com", fields: [{ selector: "#search", text: "query" }] }

// Append text without clearing
{ url: "https://example.com", fields: [{ selector: "#notes", text: " additional text", clear: false }] }

// Fast form fill without HTML return
{
  url: "https://example.com/signup",
  fields: [
    { selector: "#firstName", text: "John" },
    { selector: "#lastName", text: "Doe" },
    { selector: "#email", text: "[email protected]" }
  ],
  returnHtml: false
}

**错误处理：**如果某个字段填写失败，响应会说明：

• 失败的字段编号（例如，“第 2 个字段（共 3 个）填写失败”）
• 已成功填写的字段
• 明确提示不要重新输入已填写的字段

---

browser_get_current_html

从已加载的页面获取当前 HTML，不会导航或重新加载页面。由于只提取当前 DOM 状态，因此比 browser_fetch_webpage 快得多。交互（点击、输入）后可使用此工具，高效获取更新后的页面内容。

**⚠️ 注意：**必须先通过 browser_fetch_webpage 加载页面。

参数：

• url（字符串，必填）- 页面 URL（必须与先前抓取的页面匹配）
• removeUnnecessaryHTML（布尔值，可选，默认值：true）- 是否移除不必要的 HTML，以将体积缩小约 90%

示例：

// Get current HTML after interactions
{ url: "https://example.com" }

// Get full HTML without cleanup
{ url: "https://example.com", removeUnnecessaryHTML: false }

性能对比：

• browser_fetch_webpage：2-5 秒（完整重新加载页面）
• browser_get_current_html：0.1-0.3 秒（仅提取 HTML）✅

---

browser_scroll_page

在已加载的页面中滚动。可在使用 browser_take_screenshot 截取页面不同部分前调用，也可在交互前将元素滚动到可见位置。支持多种滚动模式：

• 按方向滚动：按指定像素量向上、下、左或右滚动
• 滚动到元素：滚动至特定元素可见
• 滚动到位置：滚动到绝对坐标

**⚠️ 注意：**必须先通过 browser_fetch_webpage 加载页面。

参数：

• url（字符串，必填）- 页面 URL（必须与先前抓取的页面匹配）
• direction（字符串，可选）- 滚动方向：up、down、left、right。与 amount 配合使用。
• amount（数字，可选，默认值：500）- 沿指定方向滚动的像素数（约为半个视口）
• selector（字符串，可选）- 要滚动到视图中的元素的 CSS 选择器。此时会忽略方向和滚动量。
• x（数字，可选）- 绝对水平滚动位置。与 y 配合使用。
• y（数字，可选）- 绝对垂直滚动位置。与 x 配合使用。

示例：

// Scroll down by 500px (default)
{ url: "https://example.com", direction: "down" }

// Scroll down by 1000px
{ url: "https://example.com", direction: "down", amount: 1000 }

// Scroll an element into view
{ url: "https://example.com", selector: "#footer" }

// Scroll to specific position
{ url: "https://example.com", x: 0, y: 2000 }

// Scroll to top of page
{ url: "https://example.com", x: 0, y: 0 }

**返回值：**当前滚动位置、页面尺寸和视口大小，可用于了解当前在页面上的位置。

---

browser_take_screenshot

对已加载的页面截图，以供视觉分析。当 HTML 解析不足以满足需求时很有用——例如页面包含图表、图片、复杂布局、弹出窗口或难以仅从 HTML 理解的视觉内容。返回 PNG 图片。

**⚠️ 注意：**必须先通过 browser_fetch_webpage 加载页面。

参数：

• url（字符串，必填）- 页面的 URL（必须与之前获取的页面匹配）
• fullPage（布尔值，可选，默认值：false）- 截取整个可滚动页面，而不仅仅是视口

示例：

// Capture viewport screenshot (default)
{ url: "https://example.com" }

// Capture full scrollable page
{ url: "https://dashboard.example.com", fullPage: true }

使用场景：

• HTML 难以解析时，查看页面布局
• 截取图表、曲线图或数据可视化内容
• 调试弹出窗口、模态框或覆盖层
• 理解视觉反馈（高亮、动画）
• 查看是什么阻止了元素点击

---

browser_close_tab

关闭与给定 URL 的主机名对应的浏览器标签页。从标签页池中移除该页面，并在下次访问该主机名时强制启动新会话。适用于清除身份验证状态、管理内存或重新开始访问某个域名。

**⚠️ 注意：**使用精确的主机名匹配（www.example.com 和 example.com 会被视为不同的标签页）。

参数：

• url（字符串，必填）- 要关闭其对应标签页的主机名的 URL

示例：

// Close tab for a domain
{
  url: 'https://example.com';
}

// This will close the tab for portal.azure.com
{
  url: 'https://portal.azure.com/dashboard';
}

使用场景：

• 清除身份验证/会话状态
• 释放浏览器内存
• 在新登录前重置为初始状态

Microsoft Word Online 插件

已启用的 word 插件可读取和替换托管在 SharePoint 或 OneDrive 上、已通过身份验证的 Word Online 文档中的内容。使用 browser_fetch_webpage 打开文档，然后通过 browser_plugin_info 和 browser_plugin_action 发现或执行操作。

操作	用途
open_document	打开文档 URL，安全地将 SharePoint 托管的编辑器提升为正式编辑器，并验证编辑/查看模式
read_document	返回有界的已渲染文档文本和结构元数据
replace_document_text	用纯文本替换整个文档
replace_document_html	用经过清理的富 HTML 和纯文本回退内容替换整个文档
insert_document_text	在文档开头或末尾插入纯文本，不替换现有内容
insert_document_html	在文档开头或末尾插入经过清理的富 HTML，不替换现有内容
import_markdown	按绝对文件路径导入本地 Markdown 文件和本地图片
export_markdown	将完整文档导出到本地 Markdown 路径和同级图片文件夹
find_text	搜索完整文档，并可选择是否区分大小写和匹配整个单词
replace_text	使用 Word 的原生文档模型，精确替换一次或所有匹配项
get_document_info	读取标题、模式、字数、渲染布局和保存状态
get_outline	读取 Word 的原生标题大纲
read_range	跳转到标题并读取已渲染的段落范围
get_text_context	检查某个匹配项的原生搜索上下文
insert_at	在完全匹配的文本之前或之后插入文本
replace_range / delete_range	替换或删除一个锚定匹配项
format_range	对锚定文本应用粗体、斜体、下划线或删除线
list_tables / read_table / update_table_cell	检查并安全地更新已渲染的表格
list_links / add_link / update_link / remove_link	检查和编辑已渲染的超链接
list_comments / add_comment / resolve_comment	使用 Word 批注
get_state	报告编辑器模式、布局计数、有界文本检查结果以及 Word 的保存信号
wait_for_save	要求布局保持稳定、可选地匹配前缀/后缀，并确认 Word 处于 Saved 状态
close_document	确认保存后关闭 Word 标签页
支持的入口包括 https://word.cloud.microsoft/、HTTPS SharePoint/OneDrive Word 链接，以及 *.officeapps.live.com 下的 Word 编辑器主机。插件使用现有的浏览器会话；请直接在浏览器中完成登录、多重身份验证或同意授权。

分发富 HTML 更新前，会移除活动内容、事件处理程序、嵌入资源、表单、图像和不安全的 URL 协议。图像方面，import_markdown 是例外：它会读取 Markdown 引用的受支持本地图像文件，验证其类型和大小，并通过受限的 Word 剪贴板操作将其嵌入。Markdown 输入中的远程图像和数据 URL 图像会被拒绝。源内容和验证内容会在内存中处理，不会由修改操作返回。该插件不会暴露 SharePoint WOPI 访问令牌、Cookie 或授权标头。

使用 import_markdown 时，请提供绝对路径 sourcePath，并将 placement 设为 replace、start 或 end。大型文档会按 Markdown 块边界拆分，而不是通过 MCP 请求发送。使用 export_markdown 时，请提供绝对路径 outputPath；对于 D:\docs\guide.md，提取的图像会写入 D:\docs\guide.assets\，并在可用时保留 Word 提供的文件名。该操作返回路径、数量和未解析图像元数据，而非导出的内容。除非 overwrite 为 true，否则不会替换现有 Markdown 文件。

导入以及整篇文档的文本/HTML 编辑会使用原生键盘导航，并将 Word 的全文剪贴板文本与预期结果进行比对，再报告成功或插入下一块内容。replace_text、replace_range、delete_range 及其表格/锚定文本调用方也会验证预期文本，同时保留无关内容。粘贴事件确认或单击“替换”按钮，都不能证明内容已更改。验证会重试暂时不可用的剪贴板读取；其受限的剪贴板等待时间和轮询等待时间会根据预期文档大小进行调整，并会规范化布局空白；但这不能证明富文本格式、图像保真度、批注锚点或持久化状态正确。请另行检查内置的 Normal/Heading 样式和富内容，然后使用 wait_for_save。如果无法复制全文，这些编辑会拒绝继续，并在可用时报告最近一次剪贴板读取失败的原因。

未经验证的修改会报告结果未知，而不会声称文档未更改。部分导入会指出停止的块，以及其结果文本已通过验证的块数。发生错误或 MCP 超时后，请勿自动重复或追加操作：应先检查受影响的内容和保存状态。目前尚未实现自动恢复和跨会话操作跟踪。

请按顺序运行 Word 操作。在单个服务进程中，重叠的 Word 插件操作会被拒绝并报告忙碌，包括会移动焦点、导航或选择文本的读取操作。即使调用方超时，锁也会一直持有，直到当前操作结束。该锁不会协调不同的 MCPBrowser 进程、通用浏览器工具以及人工/共同编辑者的输入；请避免同时编辑同一文档。

read_document 支持通过 offset 和 maxCharacters 分块读取。它反映 Word 当前呈现的页面，并会报告 mayBePartial: true，因为 Word 会对大型文档进行虚拟化处理。如果 Word 的保存指示器不可用，wait_for_save 会失败，而不会假定内容已持久化。

对于大型文档，优先使用 find_text 和 replace_text，而不是读取并重建文件。replace_text 会保留未受影响的内容和格式，支持基于 1 的匹配项序号或 replaceAll，并可要求提供 expectedMatchCount，以便在编辑存在歧义或内容已过时时失败且不更改文档。 对于“根据 Markdown 更改更新 Word”，请对实际更改的文本进行定向替换，最好使用 expectedMatchCount: 1。除非用户明确要求替换整个正文，否则不要使用 import_markdown 和 placement: replace。没有自动 Markdown 合并或基线管理工作流。不得仅为匹配源文件而覆盖独立进行的 Word 编辑；请报告冲突。原生定向编辑会保留无关内容，但编辑前请检查锚定在已更改或删除文本上的审阅批注——无法保证这些锚点上的批注会被保留。

表格和链接的枚举范围仅限当前渲染的页面，因为 Word 会对大型文档进行虚拟化。请先使用 get_outline、read_range 或 find_text 导航到相关区域。定位器存在歧义时，锚定式变更会失败，除非提供出现次数或预期匹配数。

开发 Actions

每个 action 都使用 src/core/actions.js 中的共享契约：tool 包含其元数据和架构，response 指定成功时的 MCPResponse 类型，而 handler 包含实现。调用方通过 execute() 调用 action；如果 handler 返回的不是 MCPResponse，则会被拒绝。每个 actions/ 文件夹都有一个导出完整 ACTIONS 数组的 index.js；注册代码使用该数组，而不是重新构建 action 列表。

每个 action 模块恰好有一个公共导出：其 CoreAction 或 PluginAction 描述符。工具架构、响应类和 handler 都是私有的，可通过描述符的 tool、response 和 handler 属性访问。每个描述符还有一个不可变的 id，其值等于 tool.name，便于调用方和测试从文件夹的 ACTIONS 数组中选择该 action。

export const FETCH_WEBPAGE_ACTION = new CoreAction({
  tool: FETCH_WEBPAGE_TOOL,
  response: FetchPageSuccessResponse,
  handler: fetchPage,
});

核心 action 可以添加 cli 对象来启用 CLI；如果一个 action 提供多个命令，也可以添加数组。CLI 注册表会从核心 ACTIONS 数组生成其条目，因此无需单独注册命令。

插件接口版本 2 会在每个插件 handler 旁边导出一个 PluginAction。现有的参数元数据会转换为兼容 MCP 的 inputSchema，同时 name、description 和 params 仍可用于插件发现：

// plugins/example/actions/list-items.js
export async function listItems({ page, params }) {
  return new MyPluginResponse(...);
}

export const listItemsAction = new PluginAction({
  name: 'list_items',
  description: 'List items from the current page',
  params: [{ name: 'limit', type: 'number', required: false, default: 10 }],
  response: MyPluginResponse,
  handler: listItems
});

action 文件夹的 index.js 会将这些描述符导入 ACTIONS。生产模块使用该文件夹的索引，而不是导入单个 action 文件。为便于隔离，测试可以导入单个 action 模块，但该模块仍只公开其描述符；对 handler、tool 和 response 的访问都通过该对象进行。

每个插件级别的 index.js 恰好有一个公共导出：包含其清单、检测函数、actions 和信息提供程序的 CorePlugin 描述符。生产代码只能通过 src/plugins/index.js 导出的 PLUGINS 数组访问插件；在该数组中添加或移除条目即可启用或禁用相应插件。只有插件专属测试会直接导入单个插件入口点。

export const EXAMPLE_PLUGIN = new CorePlugin({
  manifest,
  matchesPage,
  actions: ACTIONS,
  getInfo,
});

插件 handler 接收 { page, params }，并且必须返回声明的响应类型或其他 MCPResponse，例如 ErrorResponse。action 边界会拒绝原始对象。

CLI 模式

MCPBrowser 也可作为独立命令行工具使用，便于通过 shell 脚本、CI/CD 流水线或使用 shell 命令的 AI Agent（例如 GitHub Copilot CLI）调用。

# Show help
mcpbrowser --help

# Fetch a page (handles auth, SSO, SPAs automatically)
mcpbrowser fetch https://eng.ms/docs/my-page

# Fetch with raw HTML output
mcpbrowser fetch https://github.com --browser chrome --raw

# Take a screenshot
mcpbrowser screenshot https://example.com --output page.png --full-page

# Click an element on a loaded page
mcpbrowser click https://example.com --selector "#login-btn"

# Type into a form field
mcpbrowser type https://example.com --selector "input[name=q]" --text "search query"

# Execute JavaScript
mcpbrowser exec https://example.com --script "document.title"

# Get current HTML of a loaded page
mcpbrowser html https://example.com

**CLI 与 MCP 模式：**不带参数运行时，MCPBrowser 会作为 MCP 服务启动（通过 stdin/stdout 传输 JSON-RPC）。使用子命令运行时，它会执行命令并退出——无需 MCP 协议。

配置（可选）

高级设置的环境变量：

变量	描述	默认值
CHROME_PATH	Chrome/Edge/Brave 的路径	自动检测
CHROME_USER_DATA_DIR	浏览器配置文件目录	%LOCALAPPDATA%/ChromeAuthProfile
CHROME_REMOTE_DEBUG_PORT	DevTools 端口	9222

可观测性与日志记录

MCPBrowser 会记录所有操作，帮助你了解正在发生的情况：

[MCPBrowser] browser_fetch_webpage called: url=https://example.com
[MCPBrowser] Tab created: example.com
[MCPBrowser] Navigating to: https://example.com
[MCPBrowser] Navigation complete: https://example.com (1234ms)
[MCPBrowser] SPA detected: React, minimal content (0 chars)
[MCPBrowser] SPA content ready
[MCPBrowser] browser_fetch_webpage completed: https://example.com

错误消息会以 ❌ 标记：

[MCPBrowser] ❌ browser_fetch_webpage failed: net::ERR_NAME_NOT_RESOLVED
[MCPBrowser] ❌ No open page found for example.com

日志会输出到 stderr，以免干扰 stdout 上的 MCP 协议。

故障排除

浏览器无法打开？

• 确保已安装 Chrome、Edge 或 Brave
• 尝试显式设置 CHROME_PATH

无法连接到浏览器？

• 关闭所有 Chrome 实例后重试
• 检查端口 9222 是否正在使用

身份验证未保留？

• 保持浏览器标签页打开（默认行为）
• 相关请求使用相同的域名

使用 npx / 私有 npm 注册表时出现 E401 错误？

如果项目中有 .npmrc 指向私有注册表（例如 Azure Artifacts、GitHub Packages、Artifactory），npx 会尝试从该注册表而不是 npmjs.org 获取 mcpbrowser，并因 E401 失败。

**解决方法：**在 MCP 配置的 env 块中添加 npm_config_registry：

{
  "mcpServers": {
    "mcpbrowser": {
      "command": "npx",
      "args": ["-y", "mcpbrowser@latest"],
      "env": {
        "npm_config_registry": "https://registry.npmjs.org"
      }
    }
  }
}

**替代方案：**全局安装以完全跳过 npx：

npm install -g mcpbrowser

然后在 MCP 配置中使用 "command": "mcpbrowser"，不设置 args。

链接

• GitHub
• npm
• Open VSX Registry
• VS Code Marketplace
• 问题反馈

许可证

MIT