browser-buddy

Browser Buddy

让你的编码 Agent 通过你真实登录的浏览器读取网页。

Claude Code 的 WebFetch 在大多数网站上都会收到 403 错误。让它打开文档、查看 Reddit 帖子或浏览 GitHub 问题，它都会返回 403——因为服务器端抓取器没有你的 Cookie、登录信息或会话。

Browser Buddy 是一个小型本地 MCP 桥接工具：一个 Chrome 扩展（Manifest V3）与 Python 原生消息主机通信，后者提供两个 MCP 工具。你的 Agent 读取网页时，内容与你看到的完全一致——已登录、通过机器人检测；网页只会离开你的机器并进入 Agent 的上下文。

仅使用标准库。无依赖、无云服务、无需 API 密钥。

工具

工具	功能
read_active_tab	从当前 Chrome 标签页提取可读文本（URL、标题、清理后的正文）
open_and_read_url	使用你的真实浏览器配置文件（Cookie／登录信息）在后台标签页中打开 URL，提取文本，然后关闭标签页

架构

┌─────────────┐   MCP (JSON-RPC 2.0     ┌──────────────────┐  Unix socket   ┌───────────────────┐  Native Messaging  ┌────────────────┐
│ Claude Code │ ── over stdio, NDJSON ──▶ │ browser_buddy_mcp  │ ── NDJSON ──▶ │ browser_buddy_host │ ── 4-byte LE ──▶ │ Chrome extension │
│             │ ◀────────────────────── │      .py           │ ◀──────────── │       .py          │ ◀── JSON ─────── │ (your profile) │
└─────────────┘                          └──────────────────┘                └───────────────────┘                  └────────────────┘
         ▲                                        │                                                                     │
         │                                        │  one request per socket connection;                                 │  chrome.tabs +
         └──────── page text lands here ──────────┘  host routes replies by request id                                  │  chrome.scripting
                                                                                                                        ▼
                                                                                                              real logged-in page

• 扩展（extension/）：MV3 服务工作线程。通过 chrome.runtime.connectNative 与主机保持持久连接（自动重新连接）。针对你的真实标签页执行 read_active_tab / open_and_read_url，并将提取的文本发送回来。
• 主机（host/browser_buddy_host.py）：由 Chrome 启动。在扩展（带长度前缀的标准输入／输出）和 MCP 服务（位于 $TMPDIR/browser-buddy/browser-buddy.sock 的 Unix 套接字）之间进行桥接。按 ID 关联请求，超时时间为 90 秒。
• MCP 服务（pypi/browser_buddy_mcp.py）：通过标准输入／输出手动实现 JSON-RPC 2.0（不使用 mcp 包）。将工具调用转发给主机；将网页文本作为 MCP content 返回。

安装

1. 加载扩展

1. 打开 chrome://extensions，启用开发者模式。
2. 点击加载已解压的扩展程序 → 选择 extension/ 文件夹。
3. 复制“Browser Buddy”下方显示的扩展 ID。

2. 注册原生主机

cd host
./install.sh <paste-extension-id-here>

这会将 com.browserbuddy.host.json 写入 Chrome 的 NativeMessagingHosts 目录（Linux／macOS），并指向 browser_buddy_host.py。重启 Chrome， 然后打开扩展的服务工作线程控制台——你应该会看到 [browser-buddy] native host connected。

3. 将 MCP 服务添加到 Claude Code

claude mcp add browser-buddy -- python3 /absolute/path/to/pypi/browser_buddy_mcp.py

也可以在 ~/.claude.json / 项目 .mcp.json 中配置：

{
  "mcpServers": {
    "browser-buddy": {
      "command": "python3",
      "args": ["/absolute/path/to/browser-buddy/pypi/browser_buddy_mcp.py"]
    }
  }
}

需要 Python 3.9+。无需使用 pip 安装——也可以安装已发布的 软件包：pip install browser-buddy-mcp（由 pypi/ 构建；browser-buddy-mcp 命令是入口点）。

演示

1. 在常用的 Chrome 中登录 WebFetch 无法访问的网站（例如私有 GitHub 问题、需要登录才能查看的文档）。
2. 在 Claude Code 中输入：“使用 browser-buddy 读取我的当前标签页。”
3. 或输入：“使用 browser-buddy 的 open_and_read_url 读取 。”——后台标签页会打开，提取文本后自动关闭。

为什么不直接使用抓取 API？（Firecrawl 等）

第三方抓取器（Firecrawl 等）会在服务器端抓取网页：它们没有你的 Cookie，无法绕过 SSO／2FA／登录限制，也看不到你的账户下才能看到的内容，而且按页面收费。官方的 Claude in Chrome 则走向另一个极端——提供完全自主的浏览器控制——但每次工具调用都会弹出权限对话框（每个会话要弹出几十次），且在 Chrome 网上应用店的评分只有 2.7 星。

Browser Buddy 选择了折中方案：通过你已登录的浏览器提供只读访问权限。凭据不会离开你的机器，无需按页面付费，也不会弹出一堆对话框——只需“让 Agent 看到我看到的内容”。

局限性（如实说明）

• 仅支持 Chrome/Chromium。 这个扩展是整个方案的关键；没有 Chrome，就没有工具。
• 设计上仅支持只读。 它会提取文本，但不会点击、输入或填写表单。这有助于建立信任，但也意味着验证码和交互式验证仍会阻止它。
• 文本提取采用启发式方法，并非完整的可读性引擎。大型 SPA 通常可以正常处理（我们会等待页面加载并短暂稳定），但特殊布局可能会提取出杂乱内容。
• 你的真实浏览器配置文件 = 真实的风险面。 Agent 能看到浏览器能看到的一切。只有在你信任 Agent 会话读取你的标签页时，才安装此扩展。
• MV3 服务工作线程是临时的。 扩展会自动重新连接其原生端口，但冷启动可能会让首次调用增加约 1 秒。
• 对于 Agent 来说，每个套接字连接一次只处理一个请求就足够了；此工具并非为并发抓取集群而构建。
• 长页面会在 60k 个字符处截断（并标记为 (truncated)）。

安全性：域名允许列表

open_and_read_url 会在你的真实且已登录的浏览器中打开 URL。 否则，遭到提示词注入的页面可能会诱导 Agent 访问你的邮箱或 其他敏感网站。请限制 Agent 可以打开的域名：

// ~/.config/browser-buddy/config.json
{
  "allowed_domains": ["github.com", "stackoverflow.com"]
}

条目会匹配域名及其子域名（docs.github.com 会被 github.com 覆盖）。列表为空时（默认），允许打开任何 URL，但 服务器会记录一条警告，建议你设置允许列表。列表之外的 URL 会在 打开任何内容之前被拒绝。read_active_tab 不受影响——它只会 读取你已经打开的标签页。

开发

python3 tests/test_smoke.py   # 25 tests: framing, bridge routing, MCP handlers,
                              # socket dir, domain allowlist
node --check extension/background.js

许可证

MIT——详见 LICENSE。