MCP Operator

Integrations

  • Enables search and browsing of products on Amazon through browser automation, with an example project named 'amazon-shopping' for searching items like dinner plates.

  • Integrates with OpenAI's Computer Use API to interpret and execute natural language instructions for browser automation, supporting a wide range of actions like clicking, typing, and scrolling.

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

  1. Clone this 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

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:

  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

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)
-
security - not tested
F
license - not found
-
quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

A web browser automation server that allows AI assistants to control Chrome with persistent state management, enabling complex browsing tasks through asynchronous browser operations.

  1. Features
    1. Requirements
      1. Installation
        1. Usage
          1. Executable Scripts
          2. Core Methods
          3. Additional Methods
        2. Asynchronous Workflow Pattern
          1. Persistent Browser State
            1. Project Structure
              1. Development
                1. Using MCP Inspector
              2. Security

                Related MCP Servers

                • -
                  security
                  F
                  license
                  -
                  quality
                  Enables AI agents to control web browsers via a standardized interface for operations like launching, interacting with, and closing browsers.
                  Last updated -
                  0
                  JavaScript
                • -
                  security
                  A
                  license
                  -
                  quality
                  A browser monitoring and interaction tool that enables AI applications to capture and analyze browser data through a Chrome extension, supporting functions like console monitoring, screenshots, DOM analysis, and website auditing.
                  Last updated -
                  1
                  JavaScript
                  MIT License
                • -
                  security
                  A
                  license
                  -
                  quality
                  AI-driven browser automation server that implements the Model Context Protocol to enable natural language control of web browsers for tasks like navigation, form filling, and visual interaction.
                  Last updated -
                  1
                  Python
                  MIT License
                  • Apple
                • -
                  security
                  -
                  license
                  -
                  quality
                  A Model Context Protocol server that enables AI assistants to control Chrome browsers through the Chrome DevTools Protocol, allowing for navigation, clicking, typing, and extracting page information.
                  Last updated -
                  3
                  TypeScript

                View all related MCP servers

                ID: 0junur1axn