Content
# Browser MCP
> Derived from internal Hermes project.
Agent-native browser control MCP server — Make any AI agent that supports MCP capable of browsing the web.
## Why do we need this?
Existing browser MCPs (Playwright, Puppeteer) are low-level APIs for programmers. This MCP is designed for LLM agents:
- **Accessibility tree snapshot** — The agent "sees" a readable DOM tree, not the raw HTML.
- **Ref ID interaction** — Simply use `click("@e5")` without writing CSS selectors.
- **Local execution** — No need for cloud browsers or API keys.
- **Out-of-the-box experience** — 13 tools covering browser operations, network debugging, and test case recording.
## How it works
```
MCP Client (Claude Code / Cursor / ZCode ...)
│ stdio
▼
browser-mcp (this repository, Python MCP server)
│ subprocess
▼
agent-browser CLI ──► Local Chrome (headless or headed)
```
`browser-mcp` is a thin wrapper that exposes the capabilities of the `agent-browser` CLI as MCP tools for LLM agents. Agents interact with the page using ref IDs, eliminating the need for selectors.
## Installation
### Prerequisites
Requires **Python ≥ 3.10** and **Node.js** (for installing agent-browser).
### Step 1: Install agent-browser and download Chrome
```bash
# Install CLI (requires Node.js)
npm install -g agent-browser
# Download the bundled Chrome for Testing (required for first-time installation)
agent-browser install
```
Verify:
```bash
agent-browser --version
agent-browser open example.com && agent-browser snapshot -i
# If you see a list of interactive page elements, agent-browser is ready.
```
### Step 2: Install browser-mcp
```bash
git clone https://github.com/huaka1/browser-mcp.git
cd browser-mcp
# Recommended: use a virtual environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Editable installation (also registers the `browser-mcp` command-line entry)
pip install -e .
```
Verify:
```bash
browser-mcp --help # or: python -m browser_mcp.server
```
## One-click installation (let the Agent do it for you)
If you prefer not to run the commands manually, copy the following prompt into your AI agent (Claude Code, Cursor, ZCode, etc.), and it will execute the installation, generate the configuration, and guide you through verification.
```
Please help me install and configure browser-mcp (an MCP server that allows AI agents to control browsers).
Execute the steps in order, verifying each step before proceeding to the next; if a step fails, stop and provide the reason along with repair suggestions.
【Prerequisites check】
- Run `node --version`; if it fails, prompt me to install Node.js (macOS: `brew install node`).
- Run `python3 --version` to confirm ≥ 3.10; if it fails, prompt me to install Python 3.10+.
【1. Install browser engine】
npm install -g agent-browser
agent-browser install # Download Chrome for Testing (takes about 1-2 minutes)
Verify: agent-browser open example.com && agent-browser snapshot -i
If it lists interactive page elements, it's successful.
【2. Clone and install browser-mcp】
git clone https://github.com/huaka1/browser-mcp.git ~/browser-mcp
cd ~/browser-mcp
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
Verify: `python -m browser_mcp.server` should start (or browser-mcp is in PATH).
【3. Generate MCP configuration — key: merge instead of overwrite】
- Use the absolute path of `~/browser-mcp/.venv/bin/python` as the command.
- Locate my MCP configuration file: prioritize the current project ./.mcp.json, then ~/.claude.json.
- If the file exists: parse JSON, add a new "browser" key under mcpServers (preserve other configurations).
- If it doesn't exist: create a new file and write {"mcpServers": { ... }}.
- Browser configuration content:
"browser": {
"command": "<venv python absolute path>",
"args": ["-m", "browser_mcp.server"],
"env": { "BROWSER_MCP_HEADED": "1" }
}
【4. Finalize】
Tell me to restart the MCP client to load the new configuration.
After restarting, guide me to call browser_navigate to open https://example.com for final verification —
If the page snapshot returns, it means the installation chain is complete.
```
> Note: The prompt assumes headed mode by default (`BROWSER_MCP_HEADED=1`) for easier visualization. If the old daemon is still running in headless mode, causing the window not to be visible, have the agent execute `agent-browser close --all` and retry.
## Configure MCP Client
Add a `browser` server to your MCP client configuration. The simplest way is to start using the Python module:
```json
{
"mcpServers": {
"browser": {
"command": "/your/cloned/path/browser-mcp/.venv/bin/python",
"args": ["-m", "browser_mcp.server"],
"env": {
"BROWSER_MCP_HEADED": "1"
}
}
}
}
```
> There's a template `.mcp.json.example` in the repository; copy it to `.mcp.json` and adjust the path.
The `command` must point to the **absolute path of your local venv python**, otherwise the MCP client won't find the `browser_mcp` package. If using a global `pip install`, you can simply write `"command": "browser-mcp"` and remove `args`.
### Configuration file locations for various clients
| Client | Configuration file |
|--------|--------------------|
| Claude Code | `~/.claude.json` (global) or project `.mcp.json` |
| Cursor / Windsurf | Respective MCP settings panels |
| ZCode | Project `.mcp.json` |
After configuring, restart the client and confirm that the `browser_*` tools have loaded.
### Want to see the browser window (headed mode)?
By default, it's headless, so you can't see what the browser is doing. Set the environment variable to display the window:
```json
"env": {
"BROWSER_MCP_HEADED": "1"
}
```
> ⚠️ `agent-browser` runs in daemon mode, and `--headed` only takes effect when the daemon **first starts**. If there's already a headless daemon running, the newly set headed mode will be ignored. In this case, run `agent-browser close --all` in the terminal to close the old daemon and then trigger the MCP tool call again.
## First verification
After configuring, have the agent execute a simple workflow to confirm everything is working:
- Call `browser_navigate` to open `https://example.com`.
- Call `browser_snapshot` — It should return a list of interactive page elements (links, buttons + ref IDs).
- Call `browser_vision` — It should return a page screenshot.
If all three succeed, the installation is complete.
## Tool List
### Browser Operations
| Tool | Description |
|------|-------------|
| `browser_navigate` | Navigate to URL, return page snapshot |
| `browser_snapshot` | Get page accessibility tree + ref ID |
| `browser_click` | Click element (by ref ID) |
| `browser_type` | Input text into input box |
| `browser_press` | Press keyboard key |
| `browser_scroll` | Scroll page |
| `browser_back` | Browser back |
| `browser_vision` | Take screenshot |
| `browser_console` | Get console output / execute JS |
| `browser_get_images` | List page images |
### Network Debugging
| Tool | Description |
|------|-------------|
| `browser_get_network_logs` | Get network request logs (supports URL/method/status code/type filtering) |
| `browser_get_response_body` | View request details (headers + response body) |
| `browser_intercept_request` | Intercept/simulate/block requests (block ads, mock API) |
### Test Case Recording (invisible and exportable)
| Tool | Description |
|------|-------------|
| `browser_list_steps` | List recorded steps in current session buffer |
| `browser_export_steps` | Export steps as JSONL test case, preserving login state |
> The exported JSONL can be read back by the agent, and elements can be replayed using role+name for code-free E2E regression. The export directory is specified by `BROWSER_MCP_E2E_DIR`.
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `BROWSER_MCP_HEADED` | `1` shows browser window (non-headless) | headless |
| `BROWSER_MCP_DEBUG` | `1` enables debug logs | off |
| `BROWSER_MCP_E2E_DIR` | JSONL test case export directory | none |
## License
MIT
