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
Clone this repository:
git clone https://github.com/yourusername/operator-mcp.git cd operator-mcpInstall dependencies:
pip install -e .Install Playwright browsers:
playwright install chromiumSet your OpenAI API key:
export OPENAI_API_KEY=your-api-key
Usage
Start the MCP 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 --debugrun-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 TestBrowserOperatorMethodsrun-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 packageserver.py
: MCP server implementationbrowser.py
: Browser operator implementationcua/
: Computer Use API componentsagent.py
: Agent implementationcomputer.py
: Computer interfaceutils.py
: Utility functions
run-server
: Script to run the MCP serverrun-tests
: Script to run unit and integration testsrun-test-harness
: Script to run with MCP Inspector
Development
Using MCP Inspector
For debugging, use the MCP Inspector:
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)
This server cannot be installed
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.
Related MCP Servers
- AsecurityAlicenseAqualityAI-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 -12MIT License
- -securityFlicense-qualityA 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 -42
- -securityFlicense-qualityA server that enables AI assistants to control a browser through tools, allowing them to perform web automation tasks like navigation, typing, clicking, and taking screenshots.Last updated -
- -securityAlicense-qualityA Chrome extension-based Model Context Protocol server that enables AI assistants to control your browser, leveraging your existing configurations and login states for complex automation, content analysis, and semantic search.Last updated -8,520MIT License