Browser

You have a universal browser automation MCP server built on Playwright. It lets you control Chrome programmatically using the Model Context Protocol, giving you 63 tools for multi-tab management, media control, CDP-based profiling, network analysis, security testing, and on-demand documentation. It automatically detects Chrome/Chromium, runs in an isolated browser profile, captures console output, records sessions, and can reconnect after crashes, making browser automation safe and reproducible for AI agents and MCP clients.

How to use

You use this MCP server by connecting your MCP client (such as Claude Desktop, Antigravity, Claude Code, or Gemini CLI) to a local or remote process that runs the server. Your client issues tool calls to navigate pages, interact with elements, capture screenshots, analyze network requests, inspect storage, and run advanced CDP-based diagnostics. The server handles launching or attaching to a browser, keeps a clean, isolated profile, and provides on-demand documentation for each tool when you request it.

Typical workflows include opening a page, performing actions (clicks, typing, scrolling), taking screenshots or videos of the session, and using CDP tools to profile performance, monitor network activity, or test security headers. You can run multiple tabs, capture console logs for debugging, and request exact tool details via the on-demand documentation feature.

How to install

Prerequisites: you need Node.js version 16.0.0 or newer installed on your system.

Choose an installation method and run the commands below.

# Method 1: NPM Package (Recommended)
npm install -g @ricardodeazambuja/browser-mcp-server

# Or run directly with npx (no installation needed)
npx @ricardodeazambuja/browser-mcp-server

Additional sections

Configuration and usage details below show concrete MCP server commands and how to connect from different MCP clients. Use the exact commands and paths shown to ensure correct startup and profiles.

Configuration

Environment variables you may use with the server include MCP_BROWSER_PROFILE to point to a custom isolated browser profile. If you supply a custom profile, the server will use that location for the isolated Chrome/Chromium instance.

# Example: set a custom browser profile location before starting the server
export MCP_BROWSER_PROFILE="$HOME/.mcp-browser-profile"
node src/index.js

Security

Isolated browser profile ensures the server never touches your personal Chrome data. The server runs without setup dialogs, extensions, sync, or background updates, providing a clean and reproducible environment for automation.

Troubleshooting

If you see a message about no Chrome/Chromium browser found, you can either install system Chrome/Chromium or install Playwright’s Chromium and retry. Also, you can run a health check to verify which browser mode is active and where the browser profile is located.

Development

The project uses a modular structure with a core server and tools. You can run tests, explore the source, and modify or extend tools as needed.

Available tools

browser_docs

Get detailed docs, return schemas, examples, and caveats for any tool

browser_list_pages

List all open tabs/pages

browser_new_page

Open a new tab

browser_switch_page

Switch active tab

browser_close_page

Close a tab

browser_get_media_summary

List all audio/video elements with state

browser_get_audio_analysis

Analyze audio output (volume, spectrum)

browser_control_media

Play, pause, mute, seek

browser_navigate

Navigate to a URL

browser_click

Click an element (selector-based)

browser_type

Type text into an input

browser_scroll

Scroll the page (generic)

browser_reload

Reload current page

browser_go_back

Navigate back

browser_go_forward

Navigate forward

browser_wait

Pause execution

browser_mouse_move

Move mouse to pixel coordinates

browser_mouse_click

Click at pixel coordinates

browser_mouse_drag

Drag and drop

browser_mouse_wheel

Scroll mouse wheel

browser_press_key

Send keyboard event

browser_screenshot

Capture screenshot

browser_get_text

Get text from element

browser_get_dom

Get DOM structure

browser_read_page

Get page metadata (title, URL)

browser_evaluate

Execute JavaScript in the page context

browser_console_start

Start capturing console logs

browser_console_get

Get captured logs

browser_console_clear

Clear logs and stop

browser_hover

Hover over element

browser_focus

Focus element

browser_select

Select dropdown options

browser_wait_for_selector

Wait for element to appear

browser_resize_window

Resize the browser window

browser_start_video_recording

Start session recording

browser_stop_video_recording

Stop and save recording

browser_health_check

Verify browser connection

browser_perf_start_profile

Start CPU profiling (CDP)

browser_perf_stop_profile

Get CPU profile data with summary

browser_perf_take_heap_snapshot

Capture memory snapshot

browser_perf_get_heap_usage

Current JavaScript heap statistics

browser_perf_get_metrics

Runtime metrics (DOM nodes, listeners, etc.)

browser_perf_get_performance_metrics

Web vitals (FCP, LCP, CLS, TTFB)

browser_perf_start_coverage

Track code coverage

browser_perf_stop_coverage

Get coverage results

browser_net_start_monitoring

Monitor network requests

browser_net_get_requests

Get captured requests with timing

browser_net_stop_monitoring

Stop monitoring and clear log

browser_net_export_har

Export HTTP Archive log

browser_net_get_websocket_frames

Inspect WebSocket frames

browser_net_set_request_blocking

Block URL patterns

browser_net_emulate_conditions

Network throttling

browser_sec_get_security_headers

Inspect security HTTP headers

browser_sec_get_certificate_info

TLS/SSL certificate details

browser_sec_detect_mixed_content

Find HTTP resources on HTTPS pages

browser_sec_start_csp_monitoring

Monitor CSP violations

browser_sec_get_csp_violations

Get violation log

browser_sec_stop_csp_monitoring

Stop monitoring

browser_storage_get_indexeddb

Inspect IndexedDB

browser_storage_get_cache_storage

List Cache Storage entries

browser_storage_delete_cache

Delete cache

browser_storage_get_service_workers

Service worker state

browser_storage_unregister_service_worker

Unregister worker

browser_docs

On-demand documentation for tools with parameters, return schemas, and examples