browser-control-mcp-server

MCP server that gives AI agents full browser control — navigate to any website, click, type, scroll, take screenshots, inspect DOM, and read console logs.

Works with any MCP-compatible client: Claude, Cursor, Windsurf, Cline, and more.

Features

• Navigate to any URL — public sites, localhost, web apps
• Screenshot pages and get visual feedback as PNG images
• Click buttons, links, menus, dropdowns by CSS selector
• Type into inputs, search bars, textareas, password fields
• Scroll in any direction by pixel amount
• Read DOM — get full HTML source for structural analysis
• Console logs — read JS errors, warnings, and debug output
• Custom viewports — test at desktop (1920x1080), tablet (768x1024), or mobile (375x812)
• Session persistence — cookies, login state, history maintained across calls
• Two modes: headless Puppeteer (background) or real Chrome browser (via CDP connect)
• Anti-bot bypass — spoofed user agent, no webdriver flag

Quick Start

1. Install

npm install -g browser-control-mcp-server

That's it. The installer automatically configures browser-control in all detected AI clients on your system — no manual setup needed.

Supported clients (auto-configured on install): Claude Desktop · Claude Code · Cursor · Windsurf · VS Code (Copilot/Cline) · Zed · Continue · OpenCode · Cody

Works on macOS, Windows, and Linux.

After install you'll see something like:

[browser-control-mcp] Configuring AI clients...
  ✓ Claude Desktop configured
  ✓ Cursor configured
  — Windsurf not found (skipped)
[browser-control-mcp] Done. Restart your AI client to activate browser-control.

Just restart your AI client and the browser tools are ready.

---

Manual Configuration (if needed)

If auto-setup didn't catch your client, add this to your MCP config manually:

{
  "mcpServers": {
    "browser-control": {
      "command": "npx",
      "args": ["browser-control-mcp-server"]
    }
  }
}

2. Use It

Tell your AI agent:

"Open https://example.com and take a screenshot"

"Fill out the contact form on my site and submit it"

"Check my website on mobile viewport and show me how it looks"

The agent will use the browser tools automatically.

Tools

Tool	Description
browser_select_mode	Choose headless or Chrome extension mode
browser_status	Check connection status and active sessions
browser_navigate	Open any URL with optional viewport size
browser_screenshot	Capture page as PNG image
browser_click	Click element by CSS selector
browser_type	Type text into input fields
browser_scroll	Scroll page by pixel amount
browser_get_url	Get current page URL
browser_get_dom	Get full HTML source
browser_console_logs	Read JS console output

Browser Modes

Headless Mode (Default)

Opens an invisible background browser using Puppeteer. No setup required.

• Default viewport: 1024x768
• Custom viewport: pass width and height to browser_navigate
• Anti-bot detection bypass included
• Sessions identified by sessionId — pass to all subsequent calls

Connect Mode (Optional)

Controls your real running Chrome browser via the Chrome DevTools Protocol (CDP). No extension required.

Setup:

Launch Chrome with the remote debugging port enabled:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Windows
chrome.exe --remote-debugging-port=9222

Then set connect mode in your AI agent:

browser_select_mode({ mode: "connect" })

The server connects to your running Chrome instance and controls it directly — no extension install needed.

Examples

Check a website

browser_navigate({ url: "https://example.com" })
browser_screenshot()

Test mobile layout

browser_navigate({ url: "https://example.com", width: 375, height: 812 })
browser_screenshot()

Fill and submit a form

browser_navigate({ url: "https://example.com/contact" })
browser_type({ selector: "input[name=email]", text: "user@example.com" })
browser_type({ selector: "textarea[name=message]", text: "Hello!" })
browser_click({ selector: "button[type=submit]" })
browser_screenshot()

Login to a site

browser_navigate({ url: "https://example.com/login" })
browser_type({ selector: "#username", text: "myuser" })
browser_type({ selector: "#password", text: "mypass" })
browser_click({ selector: "#login-btn" })
browser_screenshot()

Debug JavaScript errors

browser_navigate({ url: "https://example.com" })
browser_console_logs()

Tool Parameters

browser_navigate

Parameter	Type	Required	Default	Description
url	string	Yes	—	URL to navigate to
width	number	No	1024	Viewport width in pixels (headless only)
height	number	No	768	Viewport height in pixels (headless only)
sessionId	string	No	—	Reuse existing headless session
mode	string	No	—	"extension" or "headless"

browser_click

Parameter	Type	Required	Description
selector	string	Yes	CSS selector (e.g. "#btn", "button[type=submit]", ".nav-link")
sessionId	string	No	Headless session ID
mode	string	No	"extension" or "headless"

browser_type

Parameter	Type	Required	Description
selector	string	Yes	CSS selector of input element
text	string	Yes	Text to type
sessionId	string	No	Headless session ID
mode	string	No	"extension" or "headless"

browser_scroll

Parameter	Type	Required	Default	Description
x	number	No	0	Horizontal scroll (positive=right)
y	number	No	0	Vertical scroll (positive=down)
sessionId	string	No	—	Headless session ID
mode	string	No	—	"extension" or "headless"

browser_screenshot, browser_get_url, browser_get_dom, browser_console_logs

Parameter	Type	Required	Description
sessionId	string	No	Headless session ID
mode	string	No	"extension" or "headless"

browser_select_mode

Parameter	Type	Required	Description
mode	string	No	"extension" or "headless" — sets session default

browser_status

No parameters.

Viewport Presets

Device	Width	Height
Mobile (iPhone)	375	812
Mobile (Android)	360	800
Tablet (iPad)	768	1024
Laptop	1366	768
Desktop	1920	1080
4K	3840	2160

Requirements

• Node.js >= 18.0.0
• Chrome/Chromium (auto-downloaded by Puppeteer for headless mode)
• Chrome browser + extension (for extension mode only)

Development

git clone https://github.com/yogesh-joshi-0333/browser-control-mcp-server.git
cd browser-control-mcp-server
npm install
npm run build
npm test

License

MIT — Yogesh Joshi