MCPBrowser

# ✅ MCPBrowser (MCP Browser)

[![VS Code Marketplace](https://img.shields.io/badge/VS%20Code-Marketplace-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=cherchyk.mcpbrowser)
[![Open VSX](https://img.shields.io/open-vsx/v/cherchyk/mcpbrowser?logo=eclipseide&logoColor=white)](https://open-vsx.org/extension/cherchyk/mcpbrowser)
[![npm version](https://img.shields.io/npm/v/mcpbrowser.svg)](https://www.npmjs.com/package/mcpbrowser)
[![Claude Desktop](https://img.shields.io/badge/Claude-Desktop-5865F2?logo=anthropic)](https://modelcontextprotocol.io/quickstart/user)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> ⚠️ **Security Notice:** MCPBrowser extracts webpage content and provides it to your AI agent (e.g., GitHub Copilot, Claude, Kiro, Antigravity), which then sends it to the LLM provider it uses (e.g., Anthropic, OpenAI, GitHub) for processing. Make sure you trust both your agent and the LLM provider — especially when accessing pages with sensitive or private data. MCPBrowser combines private data access, untrusted content exposure, and external communication (the MCP "[lethal trifecta](https://blog.modelcontextprotocol.io/posts/2026-03-16-tool-annotations/)") — all tool annotations accurately declare these risks so MCP clients can enforce appropriate safety controls. See [MCPBrowser/docs/MCP_COMPLIANCE.md](MCPBrowser/docs/MCP_COMPLIANCE.md) for details.

> 💡 **Why MCPBrowser over Puppeteer/Playwright MCP servers?** Puppeteer and Playwright are browser automation libraries — their MCP servers give agents raw, low-level browser commands. MCPBrowser uses Puppeteer under the hood and was built specifically for AI agents, adding an intelligence layer that handles the hard parts automatically.
>
> The agent gets clean HTML (90% smaller), automatic SPA detection (React, Vue, Angular), authentication flow handling (SSO, redirects, multi-step login), form discovery with multi-field filling, structured responses with next-step guidance, domain-based tab reuse, and instant DOM re-extraction without page reloads. Each MCPBrowser tool call replaces 5-8 raw browser automation calls — a typical 4-step workflow in MCPBrowser would take 20+ calls with Puppeteer/Playwright MCP, saving tokens and making the agent significantly faster. [See full comparison below.](#why-mcpbrowser-over-puppeteerplaywright-mcp-servers)

**MCPBrowser is an MCP browser server that gives AI assistants the ability to browse web pages using a real Chrome, Edge, or Brave browser.** This browser-based MCP server lets AI assistants (Claude, Copilot, Kiro, Antigravity) access any website — especially those protected by authentication, CAPTCHAs, anti-bot restrictions, or requiring JavaScript rendering. Uses your real browser session for web automation, so you log in once, and your AI can navigate, click buttons, fill forms, and extract content from sites that block automated requests.

Built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), this web browser MCP server works seamlessly with Claude Desktop, Claude Code (CLI), GitHub Copilot, Kiro, Antigravity, and any MCP-compatible AI assistant. It handles corporate SSO, CAPTCHAs, Cloudflare protection, SPAs, dashboards, and any site that blocks automated requests. Your AI gets the same browser access you have — no special APIs, no headless browser detection, just your authenticated browser session.

Example workflow for AI assistant to use MCPBrowser

```
1. browser_fetch_webpage    → Load the login page
2. browser_type_text        → Enter username & password (multiple fields at once)
3. browser_click_element    → Click "Sign In"
4. browser_get_current_html → Extract the content after login
```



## Contents
- [Why MCPBrowser over Puppeteer/Playwright MCP servers?](#why-mcpbrowser-over-puppeteerplaywright-mcp-servers)
- [Requirements](#requirements)
- [Installation](#installation)
  - [Amp](#amp)
  - [Claude Code](#claude-code)
  - [Claude Desktop](#claude-desktop)
  - [Cline](#cline)
  - [Codex](#codex)
  - [Copilot CLI](#copilot-cli)
  - [Cursor](#cursor)
  - [Factory](#factory)
  - [Gemini CLI](#gemini-cli)
  - [Goose](#goose)
  - [Kiro](#kiro)
  - [LM Studio](#lm-studio)
  - [opencode](#opencode)
  - [OpenClaw](#openclaw)
  - [Qodo Gen](#qodo-gen)
  - [VS Code (GitHub Copilot)](#vs-code-github-copilot)
  - [VS Code Extension](#vs-code-extension)
  - [Warp](#warp)
  - [Windsurf](#windsurf)
- [MCP Tools](#mcp-tools)
  - [browser_fetch_webpage](#browser_fetch_webpage)
  - [browser_execute_javascript](#browser_execute_javascript)
  - [browser_click_element](#browser_click_element)
  - [browser_type_text](#browser_type_text)
  - [browser_get_current_html](#browser_get_current_html)
  - [browser_scroll_page](#browser_scroll_page)
  - [browser_take_screenshot](#browser_take_screenshot)
  - [browser_close_tab](#browser_close_tab)
- [CLI Mode](#cli-mode)
- [Configuration](#configuration-optional)
- [Troubleshooting](#troubleshooting)
- [For Developers](#for-developers)
- [Links](#links)
- [License](#license)

## Requirements

- Chrome, Edge, or Brave browser
- [Node.js 18+](https://nodejs.org/) (includes npm)

> **Note:** Node.js must be installed on your system. The VS Code extension and npm package both require Node.js to run the MCP server. Download from [nodejs.org](https://nodejs.org/) if not already installed.

## Why MCPBrowser over Puppeteer/Playwright MCP servers?

Puppeteer and Playwright are browser automation libraries — their MCP servers expose low-level browser commands and the agent has to handle SPAs, auth flows, messy HTML, and edge cases on its own. **MCPBrowser was built specifically for AI agents.** It uses Puppeteer under the hood and adds an intelligence layer so the agent can focus on the task instead of fighting the browser.

| | MCPBrowser | Puppeteer/Playwright MCP |
|---|---|---|
| **HTML output** | Clean, LLM-optimized (~90% smaller) — strips scripts, styles, SVGs, tracking attrs, converts relative URLs | Raw DOM |
| **SPA support** | Auto-detects React, Vue, Angular, Svelte, Next.js, Nuxt — applies framework-aware wait strategies | Agent must configure waits manually |
| **Authentication** | Detects login pages, SSO redirects, multi-step auth — follows redirect chains, two-phase timeouts (5s SSO → 20min manual) | Agent must script each auth step |
| **Form interaction** | `browser_detect_forms` discovers all fields, labels, constraints; `browser_type_text` fills multiple fields at once | One field at a time, manual selectors |
| **Response format** | Typed, structured with `nextSteps` guidance — soft vs hard failure distinction with recovery actions | Raw results, generic errors |
| **Tab management** | Domain-pooled — reuses tabs, survives browser reconnection | New context per request |
| **DOM re-extraction** | `browser_get_current_html` — instant, no reload (10-50x faster) | Must re-fetch full page |
| **Plugin system** | Detects known sites by URL/DOM patterns, offers site-specific actions with confidence scoring | N/A |
| **Built for** | AI agents | Browser test automation |
| **Agent efficiency** | 1 tool call replaces 5-8 raw browser calls — a 4-step login flow takes 4 calls instead of 20+, saving tokens and round-trips | Each step (navigate, wait, query, type, click) is a separate call |

## Installation

### Getting started

First, install MCPBrowser with your MCP client.

**Standard config** works in most tools:

```json
{
  "mcpServers": {
    "mcpbrowser": {
      "command": "npx",
      "args": ["-y", "mcpbrowser@latest"]
    }
  }
}
```

[![Install in VS Code](https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522mcpbrowser%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522mcpbrowser%2540latest%2522%255D%257D)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522mcpbrowser%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522mcpbrowser%2540latest%2522%255D%257D)

---

### Amp

Add via the Amp VS Code extension settings screen or by updating your settings.json file:

```json
"amp.mcpServers": {
  "mcpbrowser": {
    "command": "npx",
    "args": ["-y", "mcpbrowser@latest"]
  }
}
```

**Amp CLI Setup:**

```bash
amp mcp add mcpbrowser -- npx -y mcpbrowser@latest
```

---

### Claude Code

Use the Claude Code CLI to add the MCPBrowser MCP server:

```bash
claude mcp add mcpbrowser --scope user -- npx -y mcpbrowser@latest
```

Verify it's working:
```bash
claude mcp list
```

You should see:
```
mcpbrowser: npx -y mcpbrowser@latest - ✓ Connected
```

---

### Claude Desktop

Add to your config file (create it if it doesn't exist):

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json` (e.g., `C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json`)  
**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mcpbrowser": {
      "command": "npx",
      "args": ["-y", "mcpbrowser@latest"]
    }
  }
}
```

Restart Claude Desktop after saving.

---

### Cline

Follow the instruction in the section [Configuring MCP Servers](https://docs.cline.bot/mcp/configuring-mcp-servers).

Add the following to your [`cline_mcp_settings.json`](https://docs.cline.bot/mcp/configuring-mcp-servers#editing-mcp-settings-files) file:

```json
{
  "mcpServers": {
    "mcpbrowser": {
      "type": "stdio",
      "command": "npx",
      "timeout": 30,
      "args": ["-y", "mcpbrowser@latest"],
      "disabled": false
    }
  }
}
```

---

### Codex

Use the Codex CLI to a