unified-browser-mcp

Unified Browser MCP Server

A Model Context Protocol (MCP) server that combines Playwright browser automation with DevTools-style monitoring capabilities in a single browser instance.

Features

• Browser Automation: Navigate, fill forms, click elements, take screenshots
• Network Monitoring: Capture all network requests with full headers and response bodies
• Console Logging: Monitor all console messages (log, warning, error, info)
• Performance Metrics: Extract Navigation Timing API data
• Single Browser Instance: All operations work on the same browser/page for consistency

What is an MCP Server?

The Model Context Protocol (MCP) allows AI assistants like Claude to interact with external tools and services. This MCP server acts as a bridge between Claude and browser automation capabilities, running automatically in the background whenever you use Claude Desktop or Cursor.

Key Points:

• 🔄 Automatic Startup: The server launches automatically when you open Cursor/Claude Desktop
• 🔌 No Manual Running: You never need to manually start the server
• 🛠️ Tool Provider: Makes browser automation tools available to Claude
• 💬 Communication: Uses JSON-RPC over stdio to talk to Claude

Installation

Prerequisites

Before installing, ensure you have:

• Node.js (v18 or higher) - Download here
• Cursor or Claude Desktop - Download Cursor

Method 1: Using npx (Recommended - Easiest)

This is the simplest method - no cloning, no building, just one config update!

Simply add this to your MCP configuration file and restart Cursor:

{
  "mcpServers": {
    "unified-browser": {
      "command": "npx",
      "args": ["-y", "unified-browser-mcp"]
    }
  }
}

That's it! The server will be automatically downloaded and run when Cursor starts.

Note: You'll still need to install Playwright browsers once: ``bash npx playwright install chromium ``

---

Method 2: Manual Installation from Source

If you prefer to build from source or want to modify the code:

Step 1: Get the Code

Choose one of these methods:

Option A: Clone from GitHub ``bash git clone https://github.com/msawayda/unified-browser-mcp.git cd unified-browser-mcp ``

Option B: Download ZIP

1. Go to https://github.com/msawayda/unified-browser-mcp
2. Click "Code" → "Download ZIP"
3. Extract to your preferred location
4. Open terminal/command prompt in that folder

Step 2: Install Dependencies

npm install

This will install:

• @modelcontextprotocol/sdk - MCP communication layer
• playwright - Browser automation library
• TypeScript and build tools

Expected output: `` added 19 packages, and audited 20 packages in 25s found 0 vulnerabilities ``

Step 3: Build the Server

npm run build

This compiles the TypeScript code to JavaScript in the build/ directory.

Expected output: `` > unified-browser-mcp@1.0.0 build > tsc ``

You should now see a build/ folder with index.js inside.

Step 4: Install Playwright Browsers

npx playwright install chromium

This downloads the Chromium browser (~150 MB) that Playwright will use.

Expected output: `` Downloading Chromium 141.0.7390.37... Chromium downloaded to C:\Users\[username]\AppData\Local\ms-playwright\chromium-1194 ``

Note: This only needs to be done once per machine.

Configuration

Locate Your MCP Configuration File

The MCP configuration file location depends on your operating system:

| OS | Configuration File Path | |---|---| | Windows | C:\Users\[username]\.cursor\mcp.json | | macOS | ~/Library/Application Support/Cursor/mcp.json | | Linux | ~/.config/cursor/mcp.json |

For Claude Desktop (instead of Cursor):

• Windows: C:\Users\[username]\AppData\Roaming\Claude\mcp.json
• macOS: ~/Library/Application Support/Claude/mcp.json
• Linux: ~/.config/Claude/mcp.json

Add the Server Configuration

1. Open the config file in a text editor (create it if it doesn't exist)

1. Add your server to the mcpServers object:

For npx Installation (Method 1):

All Operating Systems: ``json { "mcpServers": { "unified-browser": { "command": "npx", "args": ["-y", "unified-browser-mcp"] } } } ``

Simple! Same config works on Windows, macOS, and Linux.

For Manual Installation (Method 2):

Windows Example: ``json { "mcpServers": { "unified-browser": { "command": "node", "args": [ "C:\\Users\\YourUsername\\unified-browser-mcp\\build\\index.js" ] } } } ``

macOS/Linux Example: ``json { "mcpServers": { "unified-browser": { "command": "node", "args": [ "/Users/yourusername/unified-browser-mcp/build/index.js" ] } } } ``

Important Notes:

• ✅ Use absolute paths (full path from root)
• ✅ On Windows, use double backslashes (\\) or forward slashes (/)
• ✅ Replace YourUsername with your actual username
• ✅ Match the path to where you installed the server

1. If you already have other MCP servers, add a comma after the previous entry:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "unified-browser": {
      "command": "npx",
      "args": ["-y", "unified-browser-mcp"]
    }
  }
}

Step 5: Restart Cursor/Claude Desktop

Important: You must completely restart the application for MCP servers to load.

1. Close Cursor/Claude Desktop completely (not just the window)
2. Reopen the application
3. The MCP server will now start automatically in the background

How It Works

Automatic Server Management

When you start Cursor/Claude Desktop:

1. Cursor reads your mcp.json configuration
2. Launches the server by running: node path/to/build/index.js
3. Establishes communication via stdio (standard input/output)
4. Keeps it running in the background throughout your session
5. Shuts it down automatically when you close Cursor

You'll see this in the server logs (stderr): `` Unified Browser MCP server running on stdio ``

Using the Server

Once configured and Cursor is restarted:

1. Start a conversation with Claude in Cursor
2. The tools are automatically available - Claude can now use browser automation commands
3. Request browser actions like:

• "Launch a browser and navigate to example.com"
• "Fill out this form and monitor the network requests"
• "Take a screenshot of the current page"

1. Claude will execute using the MCP tools behind the scenes

You never need to manually start or stop the server!

Verification

Check If the Server Loaded Successfully

After restarting Cursor, you can verify the server is working:

1. Start a new chat with Claude
2. Ask: "What MCP tools do you have available?"
3. Look for: Tools like launch_browser, navigate, start_monitoring, etc.

If you see these tools, the server is running correctly! ✅

Common Installation Issues

❌ "Cannot find module '@modelcontextprotocol/sdk'"

Problem: Dependencies not installed

Solution: ``bash cd unified-browser-mcp npm install ``

❌ "build/index.js not found"

Problem: TypeScript not compiled

Solution: ``bash npm run build ``

❌ "Playwright browsers not found"

Problem: Chromium not downloaded

Solution: ``bash npx playwright install chromium ``

❌ Tools not appearing in Claude

Possible causes:

1. Wrong path in mcp.json - Double-check the absolute path
2. Didn't restart Cursor - Must fully restart, not just reload window
3. JSON syntax error - Validate your JSON at https://jsonlint.com/
4. Wrong file location - Config must be in the correct OS-specific location

Debug steps:

1. Check Cursor's developer console (Help → Toggle Developer Tools)
2. Look for MCP-related errors
3. Verify the path exists: node C:\path\to\build\index.js should output the server message

Updating

To update the server after pulling new changes:

cd unified-browser-mcp
git pull origin main  # If using git
npm install           # Install any new dependencies
npm run build         # Rebuild

Then restart Cursor/Claude Desktop.

Available Tools

Browser Lifecycle

launch_browser

Launch a new Chromium browser instance.

Parameters:

• headless (boolean, optional): Run in headless mode (default: false)
• viewport (object, optional): Set viewport size
• width (number): Viewport width (default: 1280)
• height (number): Viewport height (default: 720)

close_browser

Close the browser and cleanup all resources.

Navigation & Automation

navigate

Navigate to a URL.

Parameters:

• url (string, required): URL to navigate to
• waitUntil (string, optional): When to consider navigation complete
• Options: load, domcontentloaded, networkidle
• Default: load

fill_form_field

Fill a form field with a value.

Parameters:

• selector (string, required): CSS selector for the form field
• value (string, required): Value to fill

click_element

Click an element on the page.

Parameters:

• selector (string, required): CSS selector for the element
• waitForNavigation (boolean, optional): Wait for navigation after click (default: false)

submit_form

Submit a form by clicking a submit button or form element.

Parameters:

• selector (string, required): CSS selector for the submit button or form

screenshot

Take a screenshot of the page or a specific element.

Parameters:

• fullPage (boolean, optional): Capture full scrollable page (default: false)
• selector (string, optional): CSS selector to screenshot specific element

evaluate_script

Execute JavaScript code in the page context.

Parameters:

• script (string, required): JavaScript code to execute

Monitoring & DevTools

start_monitoring

Start capturing network requests and console messages.

Parameters:

• clearPrevious (boolean, optional): Clear previously captured data (default: true)

get_network_requests

Get all captured network requests with full details.

Parameters:

• filter (string, optional): Filter requests by URL pattern

Returns: Array of network requests with:

• URL, method, timestamp
• Request headers and POST data
• Response status, headers, and body (text/JSON only)

get_console_messages

Get all captured console messages.

Parameters:

• type (string, optional): Filter by message type
• Options: log, warning, error, info, all
• Default: all

get_performance_metrics

Get page performance metrics from the Navigation Timing API.

Returns: Performance timing data including:

• DOM content loaded time
• Load complete time
• DOM interactive time
• DNS, TCP, request, and response times

stop_monitoring

Stop monitoring and return a summary of captured data.

Returns: Summary with total counts and breakdowns by status/type

Example Usage

Here's a typical workflow for automating a form submission while monitoring network activity:

1. launch_browser
   - headless: false

2. navigate
   - url: "https://example.com/contact"

3. start_monitoring
   - clearPrevious: true

4. fill_form_field
   - selector: "#name"
   - value: "John Doe"

5. fill_form_field
   - selector: "#email"
   - value: "john@example.com"

6. submit_form
   - selector: "#submit"

7. get_network_requests
   - filter: "api"

8. get_console_messages
   - type: "error"

9. get_performance_metrics

10. close_browser

Use Cases

Form Automation with Network Monitoring

Automate form submissions while capturing all API calls, XHR requests, and responses.

Performance Testing

Navigate to pages and collect detailed performance metrics including timing data.

Debugging Web Applications

Monitor console errors and network failures during automated interactions.

Integration Testing

Verify that forms trigger the correct API calls with proper payloads and responses.

Technical Details

• Browser Engine: Chromium (via Playwright)
• Communication: JSON-RPC over stdio (MCP standard)
• Network Capture: Full request/response cycle with headers and bodies
• Console Capture: All message types with timestamps and locations
• Single Instance: One browser/context/page shared across all operations

Troubleshooting

Browser doesn't launch

• Ensure Playwright browsers are installed: npx playwright install chromium
• Check that Node.js is in your PATH

"Browser not launched" error

• Always call launch_browser before other operations
• If browser crashes, call launch_browser again

Network requests missing

• Call start_monitoring before navigation/interactions
• Network capture begins after start_monitoring is called

Response bodies empty

• Only text and JSON responses are captured (binary data is skipped)
• Some responses may not be available if the request hasn't completed

Development

To rebuild after making changes:

npm run build

The TypeScript compiler will output to the build/ directory.

License

MIT