Browser MCP

English · 中文

让你的 AI 真正能搜遍全网。 所有你能登录访问的站点——小红书、知乎、X、抖音、B 站、Reddit 乃至任意登录态站点——内容都能抓下来，还能在后台替你自动化操作：不无头、不逆向、不偷 Cookie。

Browser MCP 是一个本地 MCP server。它让任何支持 MCP 的 AI 助手，在你真实 Chrome 的登录态里：

• 搜遍并抓取全网任意站点的内容——公开页面、JavaScript 渲染页面，以及登录后才看得到的页面；
• 在后台 Chrome 窗口里自动化操作——点击、滚动、输入、按键、下拉，全程不切走你当前正在看的页面。

本地运行，数据不出本机：MCP server 与 Chrome 扩展都在你本机运行，只走 localhost（127.0.0.1）， 没有额外远程服务器，也不会上传你的会话。

• 登录态不泄露：扩展不申请 cookies 权限，不返回、不持久化 Cookie——登录态只在你自己的 Chrome 里被页面正常使用，从不经 MCP 传出。
• 记录与产物留本地：连接、工具调用与媒体下载状态都保存在本地；下载落盘并记录 SHA-256，不对外上报。
• 完全合规：不逆向内部接口、不绕过验证码、不窃取 Cookie、不批量抓取——行为就是一个普通登录用户 在浏览。
• 边界说明：你让 AI 读取的页面内容会作为工具结果返回给 AI 助手（这正是它的用途）；若该助手 连接的是模型 API，那部分内容会进入模型服务。但登录态与 Cookie 永不随之外泄——这点与「把内容 交给 AI」是两回事。

你能用它做什么

一句话：只要能登录访问，就都能抓。 你的 AI 可以直接在知乎、小红书、X、抖音、B 站、Reddit 乃至 任意站点里搜索、抓内容、做操作——用你已登录的状态拿到平台本身的数据。

• 直接在真实平台里搜：知乎、小红书、X、抖音、B 站、Reddit —— 用你已登录的状态，取到平台本身的数据，不靠 agent 内置搜索。
• 读任意网页：正文、页面可见文本、JavaScript 渲染内容、页面请求返回的数据，以及登录后才看得到的内容。
• 后台操作网页：在共享登录态的后台 Chrome 窗口里返回截图 + 编号可操作元素，继续点击、滚动、输入、按键、下拉、上传文件；不切走你当前的页面。
• 知乎：搜索、问题、回答、文章、邀请回答。
• 小红书：搜索、账号发布列表、笔记详情、完整评论（断点续抓）、点赞/收藏、图片/视频下载。
• 抖音：搜索、视频/图文详情、完整评论（断点续抓）、点赞/收藏、图片/视频下载。
• B 站：视频搜索、内容 meta、分 P 信息、视频或纯音频下载。
• X：帖子搜索、帖子详情。
• Reddit：帖子搜索、帖子详情、评论。
• 搜索：Google、必应、搜狗网页搜索。

当前版本为 0.15.0，版本变更见 CHANGELOG.md。

点赞、收藏、发布、发送、购买、删除等会产生外部影响的最终操作，应在执行前向用户确认。 扩展会使用当前 Chrome Profile 的登录状态访问页面，但不会向 MCP 返回或持久化 Cookie。

快速开始

1. 环境要求

• Python 3.12+
• uv
• Google Chrome

2. 安装

方式一：pip（已发布，推荐）

pip install ai-browser-mcp

装完即可直接运行 browser-mcp（Chrome 扩展已打包在安装内；扩展目录取 browser_status 返回的 extension_dir，加载方式不变）。要临时开一个指定版本，可用 uvx ai-browser-mcp。

方式二：从源码

git clone https://github.com/ywleeo/browser-mcp.git
cd browser-mcp
uv sync

下文中的 /path/to/browser-mcp 表示源码方式下本项目在本机的绝对路径；pip 安装时无需指定路径， 直接使用 browser-mcp 命令即可。

3. 加载 Chrome 扩展

1. 调用 browser_status，获取返回结果中的 extension_dir。
2. 打开 chrome://extensions。
3. 开启“开发者模式”。
4. 点击“加载已解压的扩展程序”。
5. 选择 extension_dir 对应的目录。
6. 再次调用 browser_status。

连接成功时会返回：

{
  "state": "connected",
  "connected": true,
  "bridge_port": 17880,
  "server_version": "0.15.0",
  "install_mode": "source",
  "project_root": "/path/to/browser-mcp",
  "source_commit": "<git-commit>",
  "upgrade_check_command": "uv --directory /path/to/browser-mcp run browser-mcp upgrade --check --json",
  "upgrade_apply_command": "uv --directory /path/to/browser-mcp run browser-mcp upgrade --apply --json"
}

bridge_port 也可能是 17880..17889 中的其他端口。扩展通常只需加载一次，之后会在 MCP server 启动时自动重新连接。更新扩展后若没有自动生效，请在 chrome://extensions 中点击 “重新加载”。

4. 接入你的 AI 客户端

Codex

codex mcp add browser_mcp -- \
  uv --directory /path/to/browser-mcp run browser-mcp

或直接写入 Codex MCP 配置：

[mcp_servers.browser_mcp]
command = "uv"
args = [
  "--directory",
  "/path/to/browser-mcp",
  "run",
  "browser-mcp",
]

首次添加或修改配置后重启 Codex。连接成功后，即可使用下方列出的 MCP 能力。 如需移除配置：codex mcp remove browser_mcp。

Claude Desktop

在 Claude Desktop 配置文件中加入：

{
  "mcpServers": {
    "browser-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/browser-mcp",
        "run",
        "browser-mcp"
      ]
    }
  }
}

保存配置后重启 Claude Desktop。

DeepSeek Harness (dsh)

一条命令即可把该服务注册为 dsh 原生 MCP 工具：

dsh plugin --profile web add "github:ywleeo/browser-mcp#main"

重启 dsh web 后，工具以 mcp__browser__* 形式出现（如 mcp__browser__browser_read、mcp__browser__browser_snapshot）。 这是一个"仅配置"的 dsh bundle：它把 @deepseek-ai/dsh-mcp-client 接到该服务， 而服务本身由 uvx 从 PyPI（ai-browser-mcp）拉起，所以只要 PATH 里有 uv 即可，无需本地 checkout。卸载用 dsh plugin --profile web remove "@ywleeo/dsh-browser-mcp"。

若要让 dsh 跑本地 checkout 而非 PyPI 发布版（改完代码直接验证），改用：

python3 scripts/install-dsh.py --profile web

它把一条指向当前项目目录的 insert 配置写进 ~/.dsh/profiles/<profile>/cordis.patch.yml， 按 id 判重可重复执行。uv 或项目根找不到时用 --uv / --project-dir 指定。

5. 直接开用

连接成功后，直接用自然语言告诉你的 AI 助手，例如：

“搜索知乎里关于 MCP 的回答。” “把这篇小红书笔记的全部图片下载到 /绝对路径/素材。” “读取这条抖音视频的内容和评论。” “打开这个网页，根据截图填写搜索框并点击搜索。”

完整的可直接复述的示例见 使用示例。

详细参考

升级

源码安装提供 Agent 可直接执行的安全升级命令。先检查版本与仓库状态：

uv --directory /path/to/browser-mcp run browser-mcp upgrade --check --json

确认可以升级后执行：

uv --directory /path/to/browser-mcp run browser-mcp upgrade --apply --json

升级器只接受设置了 upstream 的 Git 分支，并遵循以下保护规则：

• 工作区有未提交或未跟踪文件时拒绝升级。
• 本地与远端分叉时拒绝升级，不创建隐式 merge commit。
• 只使用 git pull --ff-only 更新源码。
• 使用 uv sync --frozen 同步锁定依赖，不修改 uv.lock。

--apply 成功并返回 restart_required: true 后，需要让客户端重新连接 MCP server。Codex 中可开启新任务或重连该 MCP；只有客户端无法单独重连时才需要重启客户端。新 MCP server 启动时会刷新扩展 bundle；已加载的 Chrome 扩展根据 build ID 自动重载，无需重新选择扩展目录。

Agent 不需要猜测项目路径。调用 browser_status 后，直接使用返回的 upgrade_check_command 和 upgrade_apply_command 即可。wheel 或其他包管理器安装会返回 install_mode: "package"，此时应使用原安装工具升级，而不是修改任意 Git 仓库。

扩展权限

• <all_urls>：用于打开调用方明确请求的公开 HTTP(S) 页面，并支持多个站点 adapter；不会 主动遍历浏览历史。
• debugger：用于捕获页面请求响应，在评论流和视觉交互中发送可信浏览器输入事件，以及把本地 文件直接写入网页的文件输入框（系统文件选择框不会弹出）。
• tabs、scripting：用于管理隔离的后台标签页并执行项目内置的固定提取脚本。
• storage、alarms：用于本地配对配置和 MV3 service worker 保活。

扩展没有申请 cookies 权限。登录态只由目标页面在当前 Chrome Profile 内正常使用，Cookie 不会通过 MCP 工具结果返回。

知乎、小红书、抖音、X 和 Reddit 工具会在执行任务前检查当前 Chrome Profile 的平台登录状态：

• 已登录：继续执行请求。
• 未登录：停止任务并返回对应平台的登录地址，客户端会提示用户先登录。
• 无法确认：停止任务，避免在登录状态不明确时继续访问目标内容。

登录状态不做缓存。用户在 Chrome 中完成登录后，可以直接重试原来的请求。

媒体下载

xhs_download 和 douyin_download 支持以下通用参数：

• media：选择 images、video 或 all。
• output_dir：可选的绝对目录；省略时保存到 Browser MCP 数据目录下的 downloads。
• overwrite：默认 false，同名文件会自动分配新文件名；只有显式设置后才覆盖。
• max_file_mb：单文件大小上限，默认 1024 MiB。

下载前会先通过当前 Chrome 登录态读取作品详情，再对页面派生的媒体 URL 执行平台 CDN 白名单、公共地址、逐跳重定向和响应媒体类型校验。文件使用 .part 临时文件流式写入， 完成后原子落盘；结果包含最终路径、字节数、Content-Type 和 SHA-256。

bilibili_download_video 与 bilibili_download_audio 使用同样的绝对目录、覆盖策略和大小 限制。B 站通常返回分离的 DASH 视频/音频轨：视频工具在系统可用 ffmpeg 时以 stream copy 无损合并为 MP4；找不到 ffmpeg 时返回两个独立轨道文件，不伪装成完整视频。纯音频工具 只保存兼容性最高的音轨。分 P 视频可在 URL 中传入 ?p=N 指定页面。

评论完整性与断点续抓

xhs_comments 与 douyin_comments 会滚动作评论流、展开回复，并观察页面自身发起的签名分页 请求。结果中的 complete 表示已观察到所有已发现评论流的终止页；limit_reached 表示因 max_comments 截断；pages_fetched 和 scrolls 可用于诊断采集过程。

热门作品的评论流要滚几分钟，超过任何 MCP 客户端愿意等待的单次调用时长，因此一次调用不追求 抓完：time_budget_seconds（默认 40 秒）到点后采集会挂起而不是失败，返回这一次新抓到的 评论，并给出 session_id。用同一 url 加上该 session_id 再调一次，即从上次停下的滚动位置 继续，不重复已抓过的评论：

• budget_exhausted 表示本次是预算到点收尾，数据完整可用，只是还没抓完；
• session_id 非空即可续抓，为空表示已经结束（抓完、达到上限或流已到底）；
• collected_total 是该会话累计已收集的评论数，配合 total 可判断进度；
• 每次返回的 items 只包含本次新增的评论，调用方自行合并。

挂起的会话会保留一个后台采集窗口，闲置 5 分钟后自动关闭，之后旧 session_id 失效，需要重新 开始采集。把 time_budget_seconds 调大可以减少续抓次数，但要确认 MCP 客户端的单次调用超时 （多数默认 60 秒）留得够。

点赞与收藏

xhs_like、xhs_collect、douyin_like、douyin_collect 接受作品 url 和期望状态 enabled（默认 true）。工具先读取当前页面状态，只有状态不一致时才点击一次，随后只轮询 验证结果；重复传入同一状态不会反向取消。传入 enabled=false 可取消点赞或收藏。

这四个工具会修改当前 Chrome Profile 对应账号的外部状态。MCP 客户端必须在每次调用前立即 取得用户明确确认；工具不会把一次未能验证的点击自动重试。

扩展排错

• state: disconnected：确认扩展已启用，然后在扩展详情页点击“重新加载”。
• 端口被占用：服务会自动尝试 17880..17889，以状态结果中的 bridge_port 为准。服务会 监控跳过 uv 后的真实 MCP Host；Host 异常退出时自动释放监听端口，不需要 Agent 猜测并 清理其他进程。
• 端口池被闲置会话占满：不会发生。MCP Host 活着但早已不用 Browser MCP 的 server 会自己退场—— 超过 BROWSER_MCP_IDLE_TIMEOUT_SECONDS（默认 3600 秒）没有任何 MCP 调用就退出并交还端口。 万一新会话启动时端口池仍然全满，它会回收其中闲置最久的那一个（需闲置超过 BROWSER_MCP_RECLAIM_IDLE_SECONDS，默认 300 秒），所以新会话总能起来。真的一个都回收不了时， 启动错误会直接列出占着每个端口的进程 PID、宿主 PID 和闲置时长，而不是只丢一句“端口已被占用”。 注意：扩展会同时连上池内每一个端口，所以“有没有连接”不代表“还在被使用”，判断依据只有真实的 MCP 调用。
• 断连不会丢掉页面上的工作：MV3 service worker 休眠导致的短暂断开只释放 debugger 附着， 标签页与窗口保留，重连后继续沿用；只有 MCP server 主动停止，或同一端口超过 5 分钟没能重连， 才会回收窗口。
• 扩展目录变化：以最新一次 browser_status 返回的 extension_dir 为准。
• 不要分享 pairing.json 或 pairing-token，它们包含本地连接凭据。

特殊进程监督器可以通过 BROWSER_MCP_OWNER_PID 显式传入宿主 PID；设置为 0 才会关闭 宿主存活监控。普通 Codex、Claude 或命令行配置无需设置此变量。

两个回收阈值同样可调：BROWSER_MCP_IDLE_TIMEOUT_SECONDS 控制闲置多久自行退场（设 0 关闭 自退），BROWSER_MCP_RECLAIM_IDLE_SECONDS 控制端口池满时一个 server 至少要闲置多久才允许被 新会话回收。回收只认「PID + 进程启动时间」完全匹配的目标，PID 被系统复用的进程只会被清掉过期 记录，绝不会收到信号。

MCP 能力

这些工具由支持 MCP 的客户端自动调用。日常使用时直接描述目标即可，不需要手动填写接口参数。

使用示例

可以直接向支持 MCP 的客户端提出自然语言请求，例如：

• “读取这个网页并总结重点。”
• “打开这个网页，根据截图填写搜索框并点击搜索。”
• “向下滚动页面，找到联系我们按钮并点击。”
• “把这篇小红书笔记的全部图片下载到 /绝对路径/素材。”
• “下载这个抖音作品的视频，返回保存路径和 SHA-256。”
• “检查我是否已经登录小红书。”
• “搜索知乎里关于 MCP 的回答。”
• “读取今天收到的知乎邀请回答。”
• “搜索小红书最近的露营笔记。”
• “读取这条小红书笔记的正文和图片。”
• “获取这条小红书笔记的全部评论和回复。”
• “点赞并收藏这条小红书笔记。”（客户端会在实际调用前确认）
• “列出我小红书账号发布的全部帖子。”
• “搜索抖音里关于牵手 APP 的作品。”
• “读取这条抖音视频的内容和评论。”
• “取消点赞这条抖音作品。”（客户端会在实际调用前确认）
• “搜索 B 站关于 OpenAI 的视频，并读取第一条视频的 meta。”
• “下载这个 B 站视频，并另外提取一份纯音频。”
• “搜索 X 上关于 OpenAI 的最新帖子。”
• “读取这条 X 帖子的正文和互动数据。”
• “搜索 Reddit 上关于 MCP 的高票帖子。”
• “读取这个 Reddit 帖子以及前 20 条评论。”
• “分别用 Google、必应和搜狗搜索 Browser MCP。”

网页每次变化后都会生成一组新的元素编号，Agent 应使用最新截图中的编号继续操作。

直接运行

如需手动启动 stdio server：

uv run browser-mcp

进程会在 stdin 等待 MCP JSON-RPC，直接在终端运行时没有输出属于正常现象。

License

MIT