MCP Operator
local-only server
The server can only run on the client’s local machine because it depends on local resources.
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
- Clone this repository:Copy
- Install dependencies:Copy
- Install Playwright browsers:Copy
- Set your OpenAI API key:Copy
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)Copyrun-tests
- Runs all tests (with options for unit or integration only)Copyrun-test-harness
- Runs the server with MCP Inspector for interactive testingCopy
Core Methods
Browser Management
- Create Browser: Initialize a new browser instanceCopy
- Navigate Browser: Direct the browser to a specified URLCopy
- Operate Browser: Execute natural language instructions for browser interactionCopy
- Close Browser: Terminate a browser instanceCopy
Job Management
- Get Job Status: Retrieve the status and result of an operation by job IDCopy
- List Jobs: View recent browser operation jobsCopy
User Notes
- Add Note: Create and store notes related to browser operationsCopy
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
A web browser automation server that allows AI assistants to control Chrome with persistent state management, enabling complex browsing tasks through asynchronous browser operations.