# Smart Browser MCP [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/zhaolibins001-svg/smart-browser  
**GitHub Stars:** 0  
**npm Downloads (last month):** 256  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/zhaolibin-smart-browser-mcp

## Description
Browser automation and API testing MCP server built on Playwright + CDP. Numbered element refs and Set-of-Mark screenshots let AI agents target the right node; flow record/replay, element memory, captcha handoff and an HTTP API test suite.

## Tools
Capabilities this server exposes over MCP:

- **browser_open** — Open website
- **browser_text** — Get page text
- **browser_snapshot** — Get page structure (title/url/button texts/inputs)
- **browser_analyze_page** — 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.
- **browser_extract_site_map** — Extract the navigation menu / link structure of the current system. Returns text/href pairs useful for building a site map or feature map.
- **browser_elements** — 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.
- **browser_mark_screenshot** — 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).
- **browser_observe** — 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).
- **browser_click** — Click element. Prefer 'ref' (from browser_elements/browser_mark_screenshot), then 'selector', then 'text'. Returns what changed after the click.
- **browser_fill** — Fill input. Prefer 'ref' (from browser_elements), then 'selector', then 'placeholder'.
- **browser_press** — Press a keyboard key, e.g. Enter, Escape, Tab, ArrowDown, Control+a. Useful for submitting forms or closing dialogs.
- **browser_scroll** — Scroll the page to load lazy content.
- **browser_select** — Select an option in a <select> dropdown by value or visible label.
- **browser_hover** — Hover over an element to trigger hover menus.
- **browser_tabs** — List all browser tabs (index, title, url, active).
- **browser_switch_tab** — Switch to a tab by index (from browser_tabs).
- **browser_new_tab** — Open a new tab, optionally with a URL.
- **browser_wait_human** — 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.
- **browser_screenshot** — Save viewport screenshot in current project (JPEG, 10s timeout, with fallback)
- **browser_set_viewport** — Set browser viewport size. Recommended: 1440x900.
- **browser_errors** — Get browser errors
- **browser_clear_errors** — Clear collected browser errors
- **browser_auto_test** — 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.
- **browser_flow_record** — 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.
- **browser_flow_run** — Replay a recorded flow by name (from browser_flow_record).
- **browser_flow_list** — List recorded flows.
- **browser_remember** — 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.
- **browser_recall** — 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.
- **browser_memory_list** — List saved page element memories.
- **browser_forget** — Delete a saved page element memory.
- **api_set_env** — 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"}.
- **api_login** — 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.
- **api_request** — 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.
- **api_assert** — 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.
- **api_test_suite** — 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.
- **api_suite_run** — Replay a previously saved API test suite by name (from api_test_suite with save=true).
- **api_suite_list** — List saved API test suites.
- **api_errors** — List recent API errors (network failures, HTTP 4xx/5xx, failed assertions).
- **api_clear_errors** — Clear the recorded API error list.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "smart-browser-mcp": {
    "command": "npx",
    "args": ["-y","@zhaolibin/smart-browser-mcp"],
    "env": {
      "BROWSER_PATH": "",
      "BROWSER_USER_DATA_DIR": "",
      "BROWSER_CDP_PORT": ""
    }
  }
}
```

**Requires environment variables:** `BROWSER_PATH`, `BROWSER_USER_DATA_DIR`, `BROWSER_CDP_PORT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Smart Browser MCP MCP server does

Smart Browser MCP MCP server gives an MCP-compatible coding assistant browser automation and API testing tools. It connects to Chrome or Edge through Playwright and the Chrome DevTools Protocol (CDP), allowing an agent to open pages, inspect content, interact with controls, manage tabs, and collect screenshots or runtime errors.

The browser observation model is built around numbered element references. After scanning a page, interactive elements receive refs such as `e1` and `e2`. Interaction tools can use those refs before falling back to selectors, placeholders, or visible text. A Set-of-Mark screenshot adds boxes and reference numbers to the page image, which can help a vision-capable model identify the intended control.

This fits the Browser Automation category for tasks such as navigating web applications, filling forms, replaying repeatable workflows, and checking a web UI alongside its HTTP API. It also supports captcha or human-verification handoff by pausing for manual handling.

## How it works

The MCP process communicates with the client over stdio. On the first browser tool call, it checks for an available CDP instance on the configured port. If one is not available, it starts a browser using the configured executable and user-data directory. Reusing a profile can preserve login state and browser extensions.

Page scans inspect visible, interactive DOM elements and create a mapping between each ref and several locating strategies. Because the mapping can become stale after page changes, the README recommends observing the page again when an interaction no longer works. Saved flows, element mappings, API environments, and test suites are written as JSON files in the current working directory.

## Setup and configuration

Node.js 18 or newer is required. Install with `npx -y @zhaolibin/smart-browser-mcp`, install the package globally with npm, or build it from source with the repository's npm scripts. The package exposes `smart-browser-mcp` and also provides `claude-browser-mcp` and `browser-mcp` command aliases.

The main environment variables are:

- `BROWSER_PATH`: browser executable path; Chrome and Edge locations can be detected automatically when omitted.
- `BROWSER_USER_DATA_DIR`: user-data directory used for persistent browser state.
- `BROWSER_CDP_PORT`: CDP debugging port, defaulting to `9222`.

Playwright's bundled browser download can also be skipped when using an installed Chrome or Edge executable.

## Tools and capabilities

Browser tools cover page opening, element observation, text extraction, DOM snapshots, semantic page analysis, site-map extraction, clicking, filling, selecting, hovering, keyboard input, scrolling, screenshots, viewport changes, and human waits. Tab tools can list, switch, and create tabs.

Smart Browser MCP MCP server also includes:

- Flow recording, listing, and replay.
- Persistent element memory with save, recall, list, and delete operations.
- Browser console error reading and clearing.
- HTTP requests, environment variables, login handling, response assertions, and test-suite execution.
- Set-of-Mark screenshots and numbered refs for model-guided targeting.

## Limitations and notes

This server relies on a locally available Chrome or Edge environment and a usable CDP port. Only one CDP instance should use a configured port at a time. Browser profile selection affects whether existing login state is available, so a changing or incorrect user-data directory can make sessions appear logged out.

Element refs describe a particular page state and may need to be regenerated after navigation, scrolling, or other DOM changes. Captcha and other human-verification steps are not automatically completed; the workflow pauses for a person and can then continue. Generated screenshots, flows, memory, API environments, and suites are stored locally under the current working directory.

_Full upstream README: https://allmcps.com/mcp/zhaolibin-smart-browser-mcp/readme_