MCP Browser Operator

A Model Control Protocol (MCP) server for browser automation that enables LLMs to control a web browser, interact with web pages, and analyze web content through a standardized JSON-RPC interface.

Features

Browser Management: Create, navigate, operate, and close browser instances
Job Management: Track status of browser operations with job IDs
Web Interaction: Execute natural language instructions using OpenAI's Computer Use API
Browser Tools: Access console logs, network activity, screenshots, and more
Auditing: Run accessibility, performance, SEO, and other web page audits

Requirements

Python 3.11+
Playwright
OpenAI API key (for the Computer Use API)

Installation

Clone this repository:

git clone https://github.com/yourusername/operator-mcp.git
cd operator-mcp

Install dependencies:
```
pip install -e .
```
Install Playwright browsers:
```
playwright install chromium
```
Set your OpenAI API key:
```
export OPENAI_API_KEY=your-api-key
```

Usage

Start the MCP server:

./run-server

The server listens for JSON-RPC requests on stdin and responds on stdout, following the MCP protocol.

Executable Scripts

run-server - Runs the MCP server (main entry point)

# Run the MCP server
./run-server

# Run with specific log directory
./run-server --log-dir /path/to/logs

# Run in debug mode
./run-server --debug

run-tests - Runs all tests (with options for unit or integration only)

# Run all tests
./run-tests

# Run only unit tests (faster)
./run-tests --unit-only

# Run only integration tests
./run-tests --integration-only

# Run with verbose output
./run-tests --verbose

# Run a specific test
./run-tests --test TestBrowserOperatorMethods

run-test-harness - Runs the server with MCP Inspector for interactive testing
```
# Run with the MCP Inspector for interactive testing
./run-test-harness
```

Core Methods

Browser Management

Create Browser: Initialize a new browser instance

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "mcp__browser-operator__create-browser",
  "params": {
    "project_name": "my-project"
  }
}

Navigate Browser: Direct the browser to a specified URL

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "mcp__browser-operator__navigate-browser",
  "params": {
    "project_name": "my-project",
    "url": "https://example.com"
  }
}

Operate Browser: Execute natural language instructions for browser interaction

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "mcp__browser-operator__operate-browser",
  "params": {
    "project_name": "my-project",
    "instruction": "Find the heading on this page and tell me what it says."
  }
}

Close Browser: Terminate a browser instance

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "mcp__browser-operator__close-browser",
  "params": {
    "project_name": "my-project"
  }
}

Job Management

Get Job Status: Retrieve the status and result of an operation by job ID

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "mcp__browser-operator__get-job-status",
  "params": {
    "job_id": "job-12345"
  }
}

List Jobs: View recent browser operation jobs

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "mcp__browser-operator__list-jobs",
  "params": {
    "limit": 10
  }
}

User Notes

Add Note: Create and store notes related to browser operations

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "mcp__browser-operator__add-note",
  "params": {
    "name": "My Note",
    "content": "Important information about this browser session"
  }
}

Additional Methods

Browser Debugging Tools

Get Console Logs: mcp__browser-tools__getConsoleLogs
Get Console Errors: mcp__browser-tools__getConsoleErrors
Get Network Logs: mcp__browser-tools__getNetworkLogs
Get Network Errors: mcp__browser-tools__getNetworkErrors
Take Screenshot: mcp__browser-tools__takeScreenshot
Get Selected Element: mcp__browser-tools__getSelectedElement
Wipe Logs: mcp__browser-tools__wipeLogs

Audit Tools

Run Accessibility Audit: mcp__browser-tools__runAccessibilityAudit
Run Performance Audit: mcp__browser-tools__runPerformanceAudit
Run SEO Audit: mcp__browser-tools__runSEOAudit
Run NextJS Audit: mcp__browser-tools__runNextJSAudit
Run Best Practices Audit: mcp__browser-tools__runBestPracticesAudit
Run Debugger Mode: mcp__browser-tools__runDebuggerMode
Run Audit Mode: mcp__browser-tools__runAuditMode

Asynchronous Workflow Pattern

Browser operations are asynchronous and use a job-based approach:

Start Operation: Call a browser method which returns a job_id
Poll for Completion: Use get-job-status until job is completed
Process Results: When job completes, access results from the job status

This approach prevents client timeouts while allowing complex browser operations to complete.

Persistent Browser State

The MCP Operator maintains persistent state when browsers are created with a project name:

Browser state (cookies, local storage, session storage) is preserved between sessions
Multiple projects can maintain independent browser states
Useful for maintaining login sessions, shopping carts, or other personalized state

Project Structure

src/mcp_operator/: Main package
- __init__.py: Package initialization
- __main__.py: Entry point for package
- server.py: MCP server implementation
- browser.py: Browser operator implementation
- cua/: Computer Use API components
  - agent.py: Agent implementation
  - computer.py: Computer interface
  - utils.py: Utility functions
run-server: Script to run the MCP server
run-tests: Script to run unit and integration tests
run-test-harness: Script to run with MCP Inspector

Development

Using MCP Inspector

For debugging, use the MCP Inspector:

# Use the included run-test-harness script
./run-test-harness

# Or directly:
npx @modelcontextprotocol/inspector ./run-server

This provides a web interface to test your MCP server.

Security

Domain blocking for potentially harmful sites
URL validation before navigation
Session isolation between different browser instances
File-based logging (no stdout to preserve MCP protocol)