Real Browser MCP

real-browser-mcp

Agentic 浏览器为 Agent 提供了一个全新的浏览器。编码 Agent 需要的是你的浏览器。

MCP + Chrome 扩展，适用于你已经打开的 Chrome：
Cookie、SSO、预发布环境会话，以及你已经复现的 Bug。

大家都在构建“Agentic 浏览器”。其中大多数会给 Agent 一个全新的浏览器：无头 Chromium、云端虚拟机，或一个没有 Cookie 的干净配置文件。

这不是编码工作流的合适工具。

你交付了一个修复。Agent 说：“完成了，请验证。” 你已经在预发布环境中打开了 Chrome，通过了 SSO，停留在恰好会出问题的页面上。 代码是 Agent 写的。它本可以在那里验证，只是看不到那个浏览器。

real-browser-mcp 是连接两者的桥梁：一个本地 MCP 服务，通过 localhost WebSocket 与 Chrome 扩展连接。你的 Agent 使用 MCP 通信，你的真实 Chrome 执行操作。会话始终保留在你的机器上。

这不是使用全新配置文件的 Playwright，不是托管式 Agent 浏览器，也不是在默认 Chrome 配置文件上加装 CDP 远程调试（Chrome 136+ 出于充分的安全原因，已禁止这种方式）。

快速开始

包含两个部分：

• MCP 服务 - 在你的机器上运行，与 AI Agent（Cursor、Claude Code、VS Code，……）通信
• Chrome 扩展 - 在真实的 Chrome 中运行并执行工具

1. 添加 MCP 服务

Cursor（一键安装）：

或者在 Cursor 设置 > MCP >“添加新的 MCP 服务”中手动添加：

{
  "mcpServers": {
    "real-browser": {
      "command": "npx",
      "args": ["-y", "real-browser-mcp"]
    }
  }
}

2. 安装 Chrome 扩展程序

或者从源代码加载：

git clone https://github.com/ofershap/real-browser-mcp.git

1. 打开 chrome://extensions 并启用开发者模式（右上角的切换开关）
2. 点击加载已解压的扩展程序，然后选择克隆的仓库中的 extension/ 文件夹

点击工具栏中的 Real Browser MCP 图标。

绿点 = 已连接。灰色 = 正在等待服务。

完成。你的 Agent 现在可以查看浏览器了。

Agent Plugins

此仓库以 Agent Plugins 1.0.0 软件包的形式发布：根目录中的 plugin.json、mcp.json 和 skills/real-browser-control/ 可帮助 Agent 判断何时应选择真实的 Chrome，而不是无头浏览器或云端 Agent 浏览器。

Claude Code 的 .claude-plugin/ 和 agent-config/ 仍用于规则和市场工作流。Agent Plugins 是跨客户端布局（MCP 和技能位于同一目录树中）。

Cursor（本地插件）： 克隆仓库，然后将其复制或创建符号链接到 ~/.cursor/plugins/local/real-browser-mcp，并重新加载窗口。你仍然需要连接 Chrome 扩展程序。下方的一键 MCP 安装只会添加服务，除非你也安装本地插件文件夹。

规范和工具：agent-plugins.org。

为什么要做这个（Agent 浏览器能力的缺口）

如果你需要在 CI 中进行可重复的自动化，请使用 Playwright。如果你希望 Agent 在你已经完成身份验证的浏览器中运行，请使用此工具。

与其他方案的比较

🧠 教会你的 Agent

Agent 开箱即用即可使用全部 18 个工具，但如果它知道该在_何时_以及_如何_串联使用这些工具，效果会更好。配置文件会教会它正确的工作流——先创建快照，再执行操作，然后验证结果。

运行一条命令：

npx real-browser-mcp --setup cursor

这会安装：

• ~/.cursor/rules/real-browser-mcp.mdc - 教会 Agent 快照优先的工作流、如何处理下拉菜单，以及何时使用截图而非快照
• ~/.cursor/commands/check-browser.md - 在 Cursor 聊天中添加 /check-browser

之后，在任意聊天中输入 /check-browser。或者只要说“检查浏览器中的结果”，Agent 就知道该怎么做。

npx real-browser-mcp --setup claude

如需手动安装或自定义规则，请参阅 agent-config/。

它能做什么

18 个工具，按用途分组。

查看

交互

导航

调试

配置

连接断开会自动处理，包括指数退避（1s 至 30s）、每 10s 执行一次 ping/pong 健康检查，以及每个工具的超时设置（点击为 5s，导航为 60s）。

{
  "mcpServers": {
    "browser-work": {
      "command": "npx", "args": ["-y", "real-browser-mcp"]
    },
    "browser-personal": {
      "command": "npx", "args": ["-y", "real-browser-mcp"],
      "env": { "WS_PORT": "9333" }
    }
  }
}

real-browser-mcp/
├── mcp-server/          MCP server (npm package, TypeScript)
│   └── src/tools/       One file per tool, registry pattern
├── extension/           Chrome extension (Manifest V3, plain JS)
│   ├── background.js    Service worker, WebSocket client, tool handlers
│   ├── content.js       Console capture
│   └── popup/           Connection status UI
├── agent-config/        Pre-built configs for Cursor + Claude Code
│   ├── cursor/          Rules and commands
│   ├── skills/          Browser automation skill
│   └── setup.mjs        One-command installer
└── tests/               Bridge + registry tests

git clone https://github.com/ofershap/real-browser-mcp.git
cd real-browser-mcp
npm install
npm run build
npm test

常见问题

这是 Agent 式浏览器吗？

不是。Agent 式浏览器通常指 Agent 使用一个新的浏览器（本地无头浏览器或云端浏览器）。real-browser-mcp 将 MCP Agent 连接到你现有的 Chrome。使用相同的配置文件、相同的标签页和相同的登录状态。

是否必须安装 Chrome 扩展？

是。MCP 服务本身无法查看或控制 Chrome。请安装 Chrome 扩展，打开弹出窗口，并等待状态显示为绿色且已连接，然后再调用工具。

它能使用我现有的登录状态和企业 SSO 吗？

可以。扩展会在你的常规 Chrome 配置文件中运行，并使用其中的 Cookie、会话和本地存储。这正是它的用途：使用你已设置好的会话进行验证，包括你手动完成的 SSO 登录。

它与 Playwright MCP 或 browser-use 有何不同？

这些技术栈以自动化工具启动的浏览器为核心（非常适合 CI 和可重复执行的任务）。Real Browser MCP 则以你已打开的浏览器为核心。需要确定性运行时使用 Playwright；需要实时会话状态时使用 Real Browser MCP。

它与 Chrome DevTools MCP 有何不同？

Chrome DevTools MCP 非常适合 DevTools 风格的调试，并可通过 CDP / autoConnect 进行连接。Chrome 136 之后，默认用户配置文件上的远程调试会被阻止，而真实登录信息恰恰保存在这个配置文件中。Real Browser MCP 使用通过 localhost WebSocket 建立的扩展桥接，而不是在该配置文件上开放调试端口。

为什么不使用云端 Agentic 浏览器？

云浏览器运行在远程机器上。你需要重新进行身份验证、离开本地 IDE 工作流，而且会话数据会留在他人的基础设施上。此项目将控制权保留在 localhost 上：MCP 服务 ↔ 扩展。工具返回页面内容时，这些内容仍会进入你的 AI 客户端；只是中间没有供应商的浏览器 SaaS。

选择 Agent 插件还是仅安装 MCP？

仅安装 MCP（Cursor deeplink 或 mcp.json）会注册服务和工具。Agent Plugins 包还会添加 plugin.json 和 real-browser-control 技能，让 Agent 知道何时应优先使用真实 Chrome，而不是无头浏览器。两种方式使用的都是同一个 npm 服务。

让 Agent 控制我的真实浏览器安全吗？

服务和扩展仅通过 localhost 上的 WebSocket 通信；不会向云端控制平面发送任何内容。不过，Agent 仍可以点击、输入并读取已连接标签页中可见的任何内容，包括已登录应用中的内容。测试不受信任的网站时，请使用专用配置文件或标签页；除非你接受相关风险，否则不要让自动化操作包含敏感数据的标签页。

参与贡献

欢迎提交错误报告、功能请求和 PR。较大的改动请先创建 issue。

作者

_{README 使用 README Builder 构建}

许可证

MIT © Ofer Shapira