Smart Browser MCP
Smart Browser MCP is a browser automation and API testing MCP server that lets AI assistants control a real Chrome/Edge browser through natural language and run HTTP interface tests.
Open and navigate pages –
browser_open,browser_new_tab, switch/list tabs.Understand pages visually and structurally – Take annotated Set-of-Mark screenshots, scan interactive elements into numbered refs (
e1,e2), extract text, DOM snapshots, page semantics, and site maps.Interact with pages – Click, fill inputs, select dropdowns, hover, press keys, scroll, set viewport, and wait for human CAPTCHA/verification handling.
Use robust element targeting – Prefer refs, then fall back to selectors, placeholders, or visible text.
Record and replay flows – Record browser action sequences and replay them later for automated testing.
Remember element mappings – Save/recall page element references across sessions.
Collect browser errors – Read and clear runtime console errors.
Test HTTP APIs – Set environment variables, log in and store tokens, send requests, assert status/fields/body content, run full API test suites.
Manage test artifacts – Save screenshots, flows, memory, and API suites as local JSON/files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Smart Browser MCP Open example.com, search for "MCP server", and click the first result"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Smart Browser MCP
面向 AI 编程助手(Claude Code / Claude Desktop / Cursor 等)的浏览器自动化 + 接口测试 MCP 服务器。 基于 Playwright + Chrome DevTools Protocol,让大模型像人一样"看得懂"页面、点得准按钮、跑得通流程。 模仿ego-lite 的windows智能浏览器工具
仓库:Gitee 主仓库 · GitHub 镜像 · npm
为什么需要它
传统浏览器自动化的痛点是:AI 只能拿到一大堆 HTML,靠猜测写 CSS 选择器,元素一变就全盘失效。
Smart Browser MCP 把「页面理解」这件事做成了模型的原生能力:
看得懂:把可交互元素扫描出来并编号(
e1、e2…),模型直接点编号,不再手写脆弱选择器;看得见:提供 Set-of-Mark(SoM)标注截图,元素框选 + 序号叠加在图上,视觉模型也能直接读懂;
记得住:页面元素映射可持久化,下次访问同一站点无需重新扫描;
可复用:一次录制、随时回放,把探索过程沉淀成可重跑的自动化流程;
闭环:内置 HTTP 接口测试工具,UI 与 API 双向验证。
Related MCP server: AI Web Tester
特性
能力 | 说明 |
元素引用(ref)机制 |
|
Set-of-Mark 截图 | 截图上叠加元素边框与序号,视觉模型可直接定位 |
智能兜底选择 | 支持 |
页面结构分析 | 文本抽取、DOM 快照、页面语义分析、站点地图提取 |
流程录制与回放 |
|
元素记忆 |
|
人机校验识别 | 自动检测验证码 / 人机验证,暂停并等待人工处理后继续 |
非阻塞式懒启动 | 首次调用工具时才拉起浏览器,不在 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 完成操作。
环境变量
变量 | 说明 | 默认值 |
| 浏览器可执行文件路径 | 自动探测 Chrome / Edge |
| 浏览器用户数据目录(保留登录态) |
|
| Chrome DevTools Protocol 调试端口 |
|
自动探测顺序:Chrome(Program Files)→ Chrome(Program Files x86)→ Edge(Program Files)→ Edge(Program Files x86)。
工具清单
页面理解
工具 | 用途 |
| 核心工具。level 1 返回带编号的可交互元素,level 2 额外返回标注截图 |
| 扫描并列出可交互元素,生成 ref 编号 |
| 生成 Set-of-Mark 标注截图 |
| 分析页面语义结构(标题、表单、导航、主要内容) |
| 提取页面文本内容 |
| 获取页面 DOM 快照 |
| 提取站点导航 / 链接结构 |
页面交互
工具 | 用途 |
| 打开 URL(首次调用触发浏览器启动) |
| 点击元素(优先 |
| 填写输入框( |
| 选择下拉框选项 |
| 鼠标悬停 |
| 键盘按键 |
| 滚动页面 |
| 等待人工处理(验证码等) |
标签页与截图
工具 | 用途 |
| 列出所有标签页 |
| 切换到指定标签页 |
| 新建标签页 |
| 页面截图 |
| 设置视口尺寸 |
调试与流程
工具 | 用途 |
| 读取页面运行时错误 |
| 清空错误记录 |
| 开始 / 停止录制操作流程 |
| 回放已录制流程 |
| 列出已保存流程 |
| 按步骤序列执行自动化测试 |
| 保存站点元素映射 |
| 载入已保存的元素映射 |
| 列出所有记忆站点 |
| 删除指定站点记忆 |
接口测试
工具 | 用途 |
| 设置接口测试环境变量(如 baseUrl、token) |
| 执行登录接口并自动保存凭证 |
| 发送任意 HTTP 请求 |
| 对响应结果做断言 |
| 定义测试套件 |
| 批量执行测试套件 |
| 列出已保存套件 |
| 读取 / 清空接口错误记录 |
工作机制

模块分层、核心机制、状态管理与扩展方式详见 docs/ARCHITECTURE.md。
AI 助手 ──stdio──> Smart Browser MCP ──Playwright/CDP──> Chrome / Edge
│
├── 懒启动:首次工具调用才拉起浏览器
├── 复用已有 CDP 实例:保留登录态与扩展
├── ref 映射表:ref(selector, 兜底定位) 双向绑定
└── 产物落盘:截图 / 流程 / 记忆 / 套件懒启动 + CDP 复用:先探测目标端口是否已有可用 CDP 实例,有则直接接管,无则按配置拉起浏览器,避免重复打开窗口、丢失登录态。
元素扫描:注入脚本遍历 DOM,筛选可见且有交互能力的元素,按序编号并记录多重定位策略。
ref 绑定:所有交互工具优先消费
ref,失效时自动降级到 selector、placeholder、可见文本,大幅提升稳定性。持久化:流程、记忆、接口套件均以 JSON 存于当前工作目录,便于版本管理与团队共享。
运行产物
MCP 在当前工作目录下生成以下内容(默认已在 .gitignore 中忽略):
路径 | 内容 |
| 截图文件 |
| 录制流程 JSON |
| 站点元素记忆 |
| 接口测试环境变量 |
| 接口测试套件 |
开发
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。
Fork 本仓库
创建分支:
git checkout -b feature/your-feature提交改动:
git commit -m "feat: 你的改动"推送分支:
git push origin feature/your-feature发起 Pull Request
许可证
Available Tools
39 toolsapi_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
Scored across 39 tools
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.
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.
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.
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
Related MCP Connectors
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Cloud browser, web extraction, screenshots, and remote CDP tools for AI agents.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables 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-
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to autonomously interact with and test web applications in a real browser, providing DOM/Accessibility tree extraction, runtime telemetry, screenshot capture, and Markdown test reports.9 npm1MIT
- AlicenseBqualityBmaintenanceEnables 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.811MIT
- AlicenseAqualityCmaintenanceEnables 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.41MIT