Browser Operator MCP server

The MCP Browser Operator is a server implementation of the Model Control Protocol (MCP) that enables large language models to control web browsers. It provides a standardized JSON-RPC interface for browser automation, web interaction, and content analysis, allowing AI models to navigate websites, execute actions, and extract information.

Requirements

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

Installation

1. Clone the repository:

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

2. Install dependencies:

   pip install -e .
   

3. Install Playwright browsers:

   playwright install chromium
   

4. Set your OpenAI API key:

   export OPENAI_API_KEY=your-api-key
   

Running the Server

Start the MCP server using the provided script:

./run-server

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

Server Options

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

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

Testing Tools

Running Tests

# 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

Using the Test Harness

For interactive testing with MCP Inspector:

./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 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:

{
  "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:

{
  "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 about 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 use a job-based approach:

1. Start Operation: Call a browser method which returns a job_id
2. Poll for Completion: Use get-job-status until job is completed
3. 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

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.