web-access-mcp 0.2.2

MCP server for browser automation over Chrome CDP

web-access-mcp

把 eze-is/web-access 里真正“可执行”的浏览器能力下沉成一个显式 MCP server，避免依赖 skill 自动激活。

当前版本已完全切到 Python 实现，安装、运行、发布都走 PyPI。

安装

推荐：

pipx install web-access-mcp

或：

pip install web-access-mcp

升级到最新版本：

pipx upgrade web-access-mcp

资源限制

• MCP 自己创建的受管 tab 最多 10 个
• 超过 10 个后，new_tab 会直接报错，防止 Chrome target 过多导致卡顿或内存爆掉
• adopt_tab 接管你原本已打开的 tab 后，不计入这 10 个配额
• close_tab 会释放配额
• 默认情况下，用户本来就打开的 Chrome tab 不计入这 10 个配额，除非你显式执行 adopt_tab

已实现能力

• browser_health: 纯 MCP server 健康检查，不触发浏览器发现、CDP 连接或浏览器授权
• browser_connect: 在浏览器侧授权后，显式完成一次 Chrome CDP 连接验证
• list_tabs: 列出当前页面 tab，并标记 isManaged 与 managedSource
• new_tab: 新建后台 tab
• close_tab: 关闭 tab
• close_all_managed_tabs: 一键关闭全部受管 tab
• close_created_tabs: 只关闭 MCP 新开的 created tab，保留接管的 adopted tab
• adopt_tab: 接管一个用户已打开的 tab
• navigate: 页面跳转并等待加载
• go_back: 后退
• page_info: 读取标题、URL、readyState
• eval: 在页面内执行 JavaScript
• click: element.click()
• click_at: 真实鼠标点击
• set_files: 给 file input 注入本地文件
• scroll: 页面滚动
• screenshot: 截图，支持返回 base64 或落盘
• network_capture_start / network_capture_get / network_capture_stop: 按 tab 捕获 Network 请求/响应，支持按域名/资源类型过滤，并可按需抓取响应 body
• safety_policy_get / safety_policy_update: 读取或更新浏览器安全策略，控制白名单、动作节奏和高风险写操作拦截
• fetch_html: 直接抓取 URL 的原始 HTML，不依赖浏览器
• fetch_url: 直接抓取 URL 并抽取标题、正文、meta 摘要
• site_pattern_lookup: 按域名或别名读取 references/site-patterns/ 里的站点经验
• search_web: 通过轻量 HTML 搜索 provider 返回标准化搜索结果
• extract_media: 从页面 DOM 提取图片、视频、source 资源 URL
• video_frame_capture: 将视频 seek 到指定时间点后截图取帧
• smart_fetch: 在 search_web、fetch_url、fetch_html、浏览器读取之间做最小自动路由，并返回风险分级、warnings、browser preference

前置条件

1. Python 3.10+
2. Chrome 已打开
3. 在 Chrome 打开 chrome://inspect/#remote-debugging
4. 勾选 Allow remote debugging for this browser instance

首次验证建议拆成两步：

1. 调 browser_health，只验证 MCP server 已 ready；这一步不会接触浏览器，也不会触发授权
2. 第一次真正要用浏览器时，再调 browser_connect 或任意浏览器工具；若浏览器侧弹出授权或尚未勾选 remote debugging，先完成授权即可

风险降低与防封

• 对同域静态请求默认增加最小时间间隔，减少连续裸 HTTP 命中简单限流的概率
• 当前浏览器路径默认启用更保守的低侵扰策略：new_tab / navigate / click / click_at / set_files / scroll 会按更慢节奏执行，更接近人工辅助操作
• 可通过 safety_policy_update 开启 domainWhitelist 白名单约束；启用后，跳转、抓包和页面动作会被限制在指定域名范围内
• 默认阻止高风险页面上的自动写操作（如 click / click_at / set_files），典型场景包括登录、验证码、支付、安全校验等路径
• network_capture_* 可选抓取响应 body；默认关闭，可通过 captureResponseBody 开启，并用 domains / resourceTypes / bodyMaxBytes 控制范围
• fetch_html 与 search_web 对瞬态网络错误做轻量 retry/backoff
• smart_fetch 会结合站点模式、登录需求、风险关键词给出 low/medium/high 风险等级，并在高风险时优先建议 browser / GUI 路径
• 这不是 stealth / 指纹伪装系统，不承诺绕过高级 bot detection；它只做 best-effort 的节奏控制与路径选择，降低误撞简单风控的概率

本地开发

开发安装：

pip install -e .

语法检查：

python -m compileall src

直接启动：

python -m web_access_mcp

Codex MCP 配置

Windows 下推荐直接指向 pip 安装生成的可执行文件，避免部分 MCP host 在 python -m ... 这条链路上出现启动异常：

[mcp_servers.web-access]
command = "C:\\Users\\Admin\\AppData\\Local\\Programs\\Python\\Python313\\Scripts\\web-access-mcp.exe"
startup_timeout_sec = 60.0

如果 web-access-mcp 已通过 pipx 或 pip 安装进 PATH，且机器里不存在旧的 npm 同名残留，也可以直接写：

[mcp_servers.web-access]
command = "web-access-mcp"
startup_timeout_sec = 60.0

若你确实要用 module 方式，也可退回：

[mcp_servers.web-access]
command = "C:\\Users\\Admin\\AppData\\Local\\Programs\\Python\\Python313\\python.exe"
args = ["-m", "web_access_mcp"]
startup_timeout_sec = 60.0

MCP 接入示例

其他支持 stdio 的 MCP 客户端也可直接这样配置：

{
  "mcpServers": {
    "web-access": {
      "command": "web-access-mcp"
    }
  }
}

发布到 PyPI

构建：

python -m build

发布：

python -m twine upload dist/*

与原 skill 的差异

• 原 skill 的“自动选择 WebSearch / WebFetch / Jina / CDP”是提示词层能力，不是脚本层能力
• 本仓库把稳定、确定、可调用的部分下沉成 MCP tools
• 现已补齐 fetch_url、fetch_html、site_pattern_lookup、search_web、extract_media、video_frame_capture 与增强版 smart_fetch，但 Jina、更多搜索 provider、站点经验写回仍未下沉
• search_web 当前基于公开 HTML 搜索结果页做 best-effort 解析，适合作为轻量入口，不等同于官方搜索 API 稳定性

设计取舍

• 运行时无第三方依赖，WebSocket 与 MCP stdio 都用 Python standard library 自行实现
• 采用 stdio + JSON-RPC 实现最小 MCP server
• stdio transport 同时兼容传统 Content-Length framing 与部分 MCP host 使用的裸 JSON over stdio
• 保留原仓库的核心思路：复用用户自己的 Chrome 登录态，而不是启动独立浏览器
• 防封策略只做风险降低，不做虚假的“绝对不封”承诺；高风险站点仍应优先人工登录、低频访问、GUI-first