Skip to main content
Glama
Smart Browser MCP

Smart Browser MCP

Smart Browser MCP

面向 AI 编程助手(Claude Code / Claude Desktop / Cursor 等)的浏览器自动化 + 接口测试 MCP 服务器。 基于 Playwright + Chrome DevTools Protocol,让大模型像人一样"看得懂"页面、点得准按钮、跑得通流程。 模仿ego-lite 的windows智能浏览器工具

仓库:Gitee 主仓库 · GitHub 镜像 · npm

Node npm Publish M8ven Verified MCP License


为什么需要它

传统浏览器自动化的痛点是:AI 只能拿到一大堆 HTML,靠猜测写 CSS 选择器,元素一变就全盘失效。

Smart Browser MCP 把「页面理解」这件事做成了模型的原生能力:

  • 看得懂:把可交互元素扫描出来并编号(e1、e2…),模型直接点编号,不再手写脆弱选择器;

  • 看得见:提供 Set-of-Mark(SoM)标注截图,元素框选 + 序号叠加在图上,视觉模型也能直接读懂;

  • 记得住:页面元素映射可持久化,下次访问同一站点无需重新扫描;

  • 可复用:一次录制、随时回放,把探索过程沉淀成可重跑的自动化流程;

  • 闭环:内置 HTTP 接口测试工具,UI 与 API 双向验证。


Related MCP server: AI Web Tester

特性

能力

说明

元素引用(ref)机制

browser_observe 扫描后返回带编号元素,后续点击/输入直接用 e1、e2

Set-of-Mark 截图

截图上叠加元素边框与序号,视觉模型可直接定位

智能兜底选择

支持 ref → selector → placeholder → 可见文本 多级降级定位

页面结构分析

文本抽取、DOM 快照、页面语义分析、站点地图提取

流程录制与回放

browser_flow_record 录制 → browser_flow_run 重放

元素记忆

browser_remember / browser_recall 跨会话保存站点元素映射

人机校验识别

自动检测验证码 / 人机验证,暂停并等待人工处理后继续

非阻塞式懒启动

首次调用工具时才拉起浏览器,不在 MCP 启动阶段占用资源

多标签页管理

列出、切换、新建标签页

控制台错误采集

自动收集页面运行时错误,支持读取与清空

接口测试套件

环境变量、登录态、请求发送、断言、套件批量执行

高度可配置

浏览器路径、用户数据目录、CDP 端口均可通过环境变量指定


快速开始

1. 安装

方式一:npx(推荐,免安装)

不需要全局安装,MCP 客户端配置里直接用 npx 调用即可,见下一节。

方式二:全局安装

npm install -g @zhaolibin/smart-browser-mcp

安装后可使用 smart-browser-mcp 命令(同时提供 claude-browser-mcp、browser-mcp 两个别名)。

方式三:从源码构建

# 任选一个源,内容一致
git clone https://gitee.com/zhaolibin001/smart-browser.git          # Gitee 主仓库
# git clone https://github.com/zhaolibins001-svg/smart-browser.git  # GitHub 镜像

cd smart-browser
npm install          # 安装依赖
npm run build        # 构建到 dist/
npm link             # 注册全局命令(可选)

环境要求:Node.js ≥ 18

可选加速:本项目通过 CDP 连接你本机已安装的 Chrome / Edge,不需要 Playwright 自带的浏览器。若安装时下载浏览器过慢,可跳过下载:

$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1; npm install -g @zhaolibin/smart-browser-mcp

2. 配置 MCP 客户端

以 Claude Code 的 settings.json 为例:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@zhaolibin/smart-browser-mcp"],
      "env": {
        "BROWSER_PATH": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
        "BROWSER_USER_DATA_DIR": "D:\\Projects\\AIchrome-profile",
        "BROWSER_CDP_PORT": "9222"
      }
    }
  }
}

如果已经全局安装(npm install -g @zhaolibin/smart-browser-mcp),也可以直接用可执行文件名(smart-browser-mcp):

{
  "mcpServers": {
    "browser": {
      "command": "smart-browser-mcp",
      "env": {
        "BROWSER_PATH": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
      }
    }
  }
}

3. 开始对话

配置完成后重启客户端,直接对 AI 说:

打开 https://example.com,帮我把顶部搜索框填上 "MCP",然后点击搜索按钮

AI 会自动调用 browser_open → browser_observe → browser_fill → browser_click 完成操作。


环境变量

变量

说明

默认值

BROWSER_PATH

浏览器可执行文件路径

自动探测 Chrome / Edge

BROWSER_USER_DATA_DIR

浏览器用户数据目录(保留登录态)

D:\Projects\AIchrome-profile

BROWSER_CDP_PORT

Chrome DevTools Protocol 调试端口

9222

自动探测顺序:Chrome(Program Files)→ Chrome(Program Files x86)→ Edge(Program Files)→ Edge(Program Files x86)。


工具清单

页面理解

工具

用途

browser_observe

核心工具。level 1 返回带编号的可交互元素,level 2 额外返回标注截图

browser_elements

扫描并列出可交互元素,生成 ref 编号

browser_mark_screenshot

生成 Set-of-Mark 标注截图

browser_analyze_page

分析页面语义结构(标题、表单、导航、主要内容)

browser_text

提取页面文本内容

browser_snapshot

获取页面 DOM 快照

browser_extract_site_map

提取站点导航 / 链接结构

页面交互

工具

用途

browser_open

打开 URL(首次调用触发浏览器启动)

browser_click

点击元素(优先 ref,其次 selector / 文本)

browser_fill

填写输入框(ref → selector → placeholder)

browser_select

选择下拉框选项

browser_hover

鼠标悬停

browser_press

键盘按键

browser_scroll

滚动页面

browser_wait_human

等待人工处理(验证码等)

标签页与截图

工具

用途

browser_tabs

列出所有标签页

browser_switch_tab

切换到指定标签页

browser_new_tab

新建标签页

browser_screenshot

页面截图

browser_set_viewport

设置视口尺寸

调试与流程

工具

用途

browser_errors

读取页面运行时错误

browser_clear_errors

清空错误记录

browser_flow_record

开始 / 停止录制操作流程

browser_flow_run

回放已录制流程

browser_flow_list

列出已保存流程

browser_auto_test

按步骤序列执行自动化测试

browser_remember

保存站点元素映射

browser_recall

载入已保存的元素映射

browser_memory_list

列出所有记忆站点

browser_forget

删除指定站点记忆

接口测试

工具

用途

api_set_env

设置接口测试环境变量(如 baseUrl、token)

api_login

执行登录接口并自动保存凭证

api_request

发送任意 HTTP 请求

api_assert

对响应结果做断言

api_test_suite

定义测试套件

api_suite_run

批量执行测试套件

api_suite_list

列出已保存套件

api_errors / api_clear_errors

读取 / 清空接口错误记录


工作机制

Smart Browser MCP 架构图

模块分层、核心机制、状态管理与扩展方式详见 docs/ARCHITECTURE.md。

AI 助手 ──stdio──> Smart Browser MCP ──Playwright/CDP──> Chrome / Edge
                          │
                          ├── 懒启动:首次工具调用才拉起浏览器
                          ├── 复用已有 CDP 实例:保留登录态与扩展
                          ├── ref 映射表:ref(selector, 兜底定位) 双向绑定
                          └── 产物落盘:截图 / 流程 / 记忆 / 套件
  1. 懒启动 + CDP 复用:先探测目标端口是否已有可用 CDP 实例,有则直接接管,无则按配置拉起浏览器,避免重复打开窗口、丢失登录态。

  2. 元素扫描:注入脚本遍历 DOM,筛选可见且有交互能力的元素,按序编号并记录多重定位策略。

  3. ref 绑定:所有交互工具优先消费 ref,失效时自动降级到 selector、placeholder、可见文本,大幅提升稳定性。

  4. 持久化:流程、记忆、接口套件均以 JSON 存于当前工作目录,便于版本管理与团队共享。


运行产物

MCP 在当前工作目录下生成以下内容(默认已在 .gitignore 中忽略):

路径

内容

browser-screenshots/

截图文件

browser-flows/

录制流程 JSON

browser-memory.json

站点元素记忆

api-env.json

接口测试环境变量

api-suites/

接口测试套件


开发

npm install

npm run dev           # 直接从源码运行
npm run build         # 构建到 dist/
npm run build:minify  # 构建并压缩
npm start             # 运行构建产物
npm test              # 契约测试(工具数量、注解完整性、只读语义)

技术栈:Node.js ≥ 18 · @modelcontextprotocol/sdk · Playwright · Zod · esbuild


常见问题

Q:浏览器没有自动启动? A:检查 BROWSER_PATH 是否指向真实存在的可执行文件;未设置时会自动探测 Chrome / Edge 的默认安装路径。

Q:登录态丢失? A:确保 BROWSER_USER_DATA_DIR 指向固定目录,该目录即持久化用户数据目录。

Q:端口被占用 / 连接失败? A:确认 BROWSER_CDP_PORT 未被其他进程占用;同一端口同时只应存在一个 CDP 实例。

Q:元素点击失效? A:页面变动后重新调用 browser_observe 刷新 ref 映射,或先用 browser_wait_human / browser_scroll 确保元素进入可视区域。


贡献

欢迎提交 Issue 与 Pull Request。

  1. Fork 本仓库

  2. 创建分支:git checkout -b feature/your-feature

  3. 提交改动:git commit -m "feat: 你的改动"

  4. 推送分支:git push origin feature/your-feature

  5. 发起 Pull Request


许可证

ISC License · 隐私政策 / Privacy Policy · 更新日志 / Changelog

Available Tools

39 tools
api_assertA

Send a request and assert on it: expectStatus (exact status code), expectFields (dot-path -> expected value, e.g. {"data.total": 10}), expectBodyContains (substring match on raw response text). Returns a clear pass/fail report; failures are also recorded and retrievable via api_errors.

Inputs: url (required), method (required), body, name, +6 more.

api_clear_errorsA

Clear the recorded API error list.

Inputs: no named parameters.

api_errorsC

List recent API errors (network failures, HTTP 4xx/5xx, failed assertions).

Inputs: limit.

api_loginA

Call a login endpoint, extract a token from the JSON response via tokenPath (dot path, e.g. "data.token"), and store it into defaultHeaders for all subsequent api_request/api_assert calls. Fails loudly if the token path is not found.

Inputs: url (required), body, method, tokenPath, +2 more.

api_requestA

Send a single HTTP request to a web API (relative URLs resolve against the baseUrl set by api_set_env) and return status, headers and body. Use this for one-off exploration; use api_assert when you also want pass/fail checks.

Inputs: url (required), method (required), body, query, +2 more.

api_set_envA

Set base URL and/or default headers used by all subsequent api_request / api_assert / api_test_suite calls. Merges with existing env unless replace=true. Typical use: set baseUrl once at the start of a session, e.g. {baseUrl: "https://localhost:5001"}.

Inputs: baseUrl, replace, defaultHeaders.

api_suite_listA

List saved API test suites.

Inputs: no named parameters.

api_suite_runA

Replay a previously saved API test suite by name (from api_test_suite with save=true).

Inputs: name (required).

api_test_suiteA

Run a list of API test cases (same shape as api_assert's inputs) in sequence and return an aggregated pass/fail report. Pass save=true with a name to persist the case list to disk for later replay via api_suite_run.

Inputs: cases (required), name, save.

browser_analyze_pageA

Analyze current page and return structured information: title, url, text, inputs, buttons, links, menus and recent console errors. Use this instead of screenshot when you only need to understand the page.

Inputs: no named parameters.

browser_auto_testC

Run browser test steps and save screenshots/errors. click/fill steps accept ref (from browser_observe), selector, or text/placeholder. For repeated flows prefer browser_flow_record/browser_flow_run.

Inputs: steps (required).

browser_clear_errorsA

Clear collected browser errors

Inputs: no named parameters.

browser_clickA

Click element. Prefer 'ref' (from browser_elements/browser_mark_screenshot), then 'selector', then 'text'. Returns what changed after the click.

Inputs: ref, text, selector.

browser_elementsA

List visible clickable elements and inputs. Each gets a short ref (e1, e2...) usable in browser_click/browser_fill/browser_select/browser_hover — prefer ref over raw selector or text to avoid ambiguity.

Inputs: no named parameters.

browser_errorsB

Get browser errors

Inputs: no named parameters.

browser_extract_site_mapA

Extract the navigation menu / link structure of the current system. Returns text/href pairs useful for building a site map or feature map.

Inputs: no named parameters.

browser_fillB

Fill input. Prefer 'ref' (from browser_elements), then 'selector', then 'placeholder'.

Inputs: value (required), ref, selector, placeholder.

browser_flow_listA

List recorded flows.

Inputs: no named parameters.

browser_flow_recordA

Record browser actions into a named reusable flow. mode=start begins recording (open/click/fill/press/scroll are captured with selectors); mode=stop saves the flow to disk for later replay with browser_flow_run.

Inputs: mode (required), name (required).

browser_flow_runA

Replay a recorded flow by name (from browser_flow_record).

Inputs: name (required).

browser_forgetB

Delete a saved page element memory.

Inputs: name (required).

browser_hoverC

Hover over an element to trigger hover menus.

Inputs: ref, text, selector.

browser_mark_screenshotA

Screenshot the viewport with numbered boxes drawn over interactive elements (Set-of-Mark). Returns the image plus number/ref -> selector mapping. Then use browser_click with the ref (e.g. e3).

Inputs: no named parameters.

browser_memory_listB

List saved page element memories.

Inputs: no named parameters.

browser_new_tabB

Open a new tab, optionally with a URL.

Inputs: url.

browser_observeA

Layered observation — use the cheapest level that suffices. level 0: lightweight status (url/title/error count/captcha flag, ~50 tokens). level 1: interactive elements with refs (same as browser_elements). level 2: annotated screenshot (same as browser_mark_screenshot).

Inputs: level.

browser_openC

Open website

Inputs: url (required).

browser_pressA

Press a keyboard key, e.g. Enter, Escape, Tab, ArrowDown, Control+a. Useful for submitting forms or closing dialogs.

Inputs: key (required).

browser_recallB

Load a saved page element map (from browser_remember) and register fresh refs for it, skipping re-observation. Returns key -> new ref mapping plus any elements whose selector no longer exists on the page.

Inputs: name (required).

browser_rememberA

Save current refs under a semantic page name for later reuse. Refs are resolved to durable selectors (+ backups) before saving, so they survive page reloads. Example: {name: "loginPage", refs: {username: "e1", password: "e2", submit: "e3"}}. Recall later with browser_recall.

Inputs: name (required), refs (required).

browser_screenshotC

Save viewport screenshot in current project (JPEG, 10s timeout, with fallback)

Inputs: name, fullPage.

browser_scrollB

Scroll the page to load lazy content.

Inputs: direction (required), amount.

browser_selectA

Select an option in a dropdown by value or visible label.

Inputs: value (required), ref, selector.

browser_set_viewportB

Set browser viewport size. Recommended: 1440x900.

Inputs: width, height.

browser_snapshotB

Get page structure (title/url/button texts/inputs)

Inputs: no named parameters.

browser_switch_tabA

Switch to a tab by index (from browser_tabs).

Inputs: index (required).

browser_tabsA

List all browser tabs (index, title, url, active).

Inputs: no named parameters.

browser_textB

Get page text

Inputs: no named parameters.

browser_wait_humanA

Wait for the user to manually solve a CAPTCHA / human-verification widget in the browser. Polls until the widget disappears or timeout (default 120s). Always tell the user you are waiting before calling this.

Inputs: timeout.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 39 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but there is some overlap among browser_snapshot, browser_analyze_page, browser_observe, browser_elements, and browser_mark_screenshot. The descriptions clarify when to use each, so an agent can disambiguate, but the boundaries are not perfectly crisp.

    Naming Consistency5/5

    All tools follow a consistent pattern of either 'browser_' or 'api_' prefix followed by snake_case action or noun (e.g., browser_click, api_assert). The naming is uniform and predictable across the entire set, making it easy to infer functionality.

    Tool Count2/5

    With 39 tools, the server is significantly over the typical 3-15 range. Even considering the broad scope of covering both browser automation and API testing, the count feels excessive and likely introduces redundancy (e.g., multiple observation and snapshot tools). This may overwhelm agents and complicate tool selection.

    Completeness5/5

    The toolset covers browser automation comprehensively: navigation, interaction, observation, screenshots, tabs, flows, memory, error handling, and human verification. API testing is also thorough, with request, assertion, suite management, and error tracking. There are no obvious critical gaps for the stated dual purpose.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to automate and debug real Chromium browsers with capabilities like screenshots, video recording, performance analysis, visual regression testing, and OCR text extraction.
      13
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents and developers to automate real Chrome/Chromium browsers through the Chrome DevTools Protocol, with token-efficient snapshots, multi-action batching, shadow DOM traversal, system-page control, extension management, and network/WebSocket inspection.
      81
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents and MCP hosts to drive a persistent headless Chromium browser through Playwright, navigating pages, mapping visible fields and actions, clicking, typing, scrolling, and capturing screenshots via stdio tool calls. It also powers a local AI Test Studio dashboard that generates and runs structured end-to-end test plans with assertions, per-step timing, and screenshot evidence.
      4
      1
      MIT