browser-agent

Runbook AI MCP 服务

一个通过 Chrome 扩展提供浏览器自动化能力的 MCP（Model Context Protocol）服务。它允许 Claude Code 等基于终端的 Agent 通过你的实时浏览器会话与任何网站交互。

属于 Runbook AI 生态系统的一部分。加入 Discord 社区，分享反馈并参与开发！

https://github.com/user-attachments/assets/a43fba64-bc40-4ef6-9840-e100203e2cf5

为什么选择 Runbook AI？

大多数基于浏览器的 MCP 工具（例如 chrome-devtools-mcp）都会在每次浏览器操作后发送整个 DOM，导致大模型上下文窗口不堪重负。

Runbook AI 与众不同：

• 优化上下文： 它会生成高度简化的 HTML 版本，剔除无用内容，同时保留关键文本和交互元素。内容精简、速度快，也不会耗尽令牌。
• 终极兜底方案： 如果某个网站没有专用的 MCP 服务（例如 Expedia、LinkedIn 或内部工具），它就能完美填补空缺。
• 隐私优先： 它完全在你的浏览器中运行。除你选择的大模型提供商外，不会进行远程调用。不会使用 eval() 或可疑脚本（由 Chrome 扩展沙盒强制保障）。
• 高效导航： 简化后的 HTML 内容不限于视口范围，让滚动和多页任务的效率更高。

安装

MCP 服务

将以下内容添加到 MCP 设置配置中：

{
  "mcpServers": {
    "runbook-ai": {
      "command": "npx",
      "args": ["-y", "runbook-ai-mcp@latest"]
    }
  }
}

Chrome 扩展

从 Chrome 网上应用店安装 Runbook AI 扩展。

在扩展侧边栏中打开扩展设置，然后启用 MCP。

设置大模型 API 密钥、模型名称和基础 URL。建议使用 Gemini 3 Flash（gemini-3-flash-preview）。可从 Google AI Studio 获取免费 API 密钥。

MCP 令牌（推荐）

如果不设置令牌，任何能够与 localhost:9003 建立 WebSocket 连接的程序都能控制你的浏览器。若要限制访问，请打开扩展设置，点击 MCP token 旁边的 Generate，然后保存。此后，扩展只会执行携带相同令牌的请求。

使用 --token 将令牌传递给 MCP 服务：

{
  "mcpServers": {
    "runbook-ai": {
      "command": "npx",
      "args": ["-y", "runbook-ai-mcp@latest", "--token", "<your token>"]
    }
  }
}

或者用于 Claude Code（设置中的 Copy setup command 会复制这一行）：

claude mcp add runbook-ai -- npx -y runbook-ai-mcp@latest --token <your token>

如果未提供 --token，服务也会读取 RUNBOOK_AI_MCP_TOKEN；在共享计算机上优先使用此方式，因为其他用户可以通过 ps 看到命令行参数。令牌缺失或错误的请求会返回 Error: invalid-mcp-token: ...。如果扩展设置中的令牌为空，则会关闭检查。

默认情况下，扩展可以访问所有网站。如果要限制访问，请前往 Chrome 扩展详情，并在“网站访问权限”设置中添加个别网站。

用法

打开 Chrome，并保持扩展侧边栏处于打开状态。

启动 MCP 服务（由 MCP 客户端调用时会自动启动）。

工具架构

该服务提供一个工具：

browser-agent

在 Chrome 浏览器中运行具备 AI 和自动化能力的任务。

参数：

• prompt（字符串，必填）：要由 AI Agent 执行的任务提示词
• maxIterations（数字，可选）：任务的 Agent 最大迭代次数（默认值：15）。每次迭代代表一个 Agent 操作（导航、点击、输入等）；对于较长的多页面任务，请提高此值。Token 预算会随之增加。
• ephemeral（布尔值，可选，默认值为 true）：每次调用都在独立的浏览器会话中运行——从全新的空白标签页开始，无法查看之前调用遗留的标签页，并会在结束时关闭其打开的所有标签页。传入 false 可从上次调用的标签页继续操作，并保持最终页面打开（例如，基于同一页面构建的多次调用工作流）。
• effort（字符串，可选，默认值为 normal）：Agent 投入的探索程度——quick（快速浏览已加载内容，将缺失的可选详情报告为“未指定”，并使用更紧凑的迭代预算）、normal（根据请求所需程度进行探索）或 thorough（遍历所有分页、打开详情页、逐一检查候选项，并使用更大的迭代预算）。各个级别均适用准确性规则。
• outputDir（字符串，可选）：Agent 生成的文件在运行 MCP 服务的机器上的保存目录（如果不存在则会创建；同名文件会被覆盖）。默认值：如果设置了 $RUNBOOK_AI_FILES_DIR，则使用其下新建的每次调用专属目录 runbook-ai-mcp/task-<timestamp>-<id>；否则使用操作系统临时目录。

文件： Agent 在运行期间保存的所有内容——写入文件的数据（例如，抓取的列表或通过 saveToFile 捕获的 API 负载）、下载内容、提取的数据集、屏幕截图——都会写入磁盘，并在结果文本末尾以绝对路径、MIME 类型和大小的形式列出。文件内容不会内嵌在结果中，因此大量数据不会占用你的上下文；请使用自己的工具读取这些文件。图像文件（≤ 4 MB）还会作为内嵌 MCP 图像内容返回，以便直接查看屏幕截图。

若要将大量数据保存为文件，请在提示词中说明，例如："... collect all orders from the account page and save them to orders.json"。

示例：

{
  "name": "browser-agent",
  "arguments": {
    "prompt": "Go to google.com and search for 'MCP protocol'"
  }
}

开发

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

架构

1. MCP Server：通过 stdio 与 MCP 客户端通信
2. WebSocket Server：在端口 9003 上监听 Chrome 扩展连接
3. Chrome Extension：执行浏览器自动化任务

调用工具时：

1. MCP 客户端通过 stdio 向 MCP 服务发送请求
2. MCP 服务通过 WebSocket 将请求转发给 Chrome 扩展
3. 扩展执行任务并返回结果
4. 结果发送回 MCP 客户端；Agent 生成的文件会写入磁盘（outputDir），其路径会附加到结果中

贡献

欢迎贡献！欢迎提交 PR。