MCP Operator

MCP 浏览器操作员

用于浏览器自动化的模型控制协议 (MCP) 服务器，使 LLM 能够通过标准化的 JSON-RPC 接口控制 Web 浏览器、与网页交互以及分析 Web 内容。

特征

• 浏览器管理：创建、导航、操作和关闭浏览器实例
• 作业管理：使用作业 ID 跟踪浏览器操作的状态
• Web 交互：使用 OpenAI 的计算机使用 API 执行自然语言指令
• 浏览器工具：访问控制台日志、网络活动、屏幕截图等
• 审计：运行可访问性、性能、SEO 和其他网页审计

要求

• Python 3.11+
• 剧作家
• OpenAI API 密钥（用于计算机使用 API）

安装

1. 克隆此存储库：
   git clone https://github.com/yourusername/operator-mcp.git cd operator-mcp
2. 安装依赖项：
   pip install -e .
3. 安装 Playwright 浏览器：
   playwright install chromium
4. 设置您的 OpenAI API 密钥：
   export OPENAI_API_KEY=your-api-key

用法

启动 MCP 服务器：

服务器按照 MCP 协议在 stdin 上监听 JSON-RPC 请求并在 stdout 上做出响应。

可执行脚本

• run-server - 运行 MCP 服务器（主入口点）
  # 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 -运行所有测试（仅提供单元或集成选项）
  # 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 - 使用 MCP Inspector 运行服务器进行交互式测试
  # Run with the MCP Inspector for interactive testing ./run-test-harness

核心方法

浏览器管理

• 创建浏览器：初始化一个新的浏览器实例
  { "jsonrpc": "2.0", "id": 1, "method": "mcp__browser-operator__create-browser", "params": { "project_name": "my-project" } }
• 导航浏览器：将浏览器定向到指定的 URL
  { "jsonrpc": "2.0", "id": 2, "method": "mcp__browser-operator__navigate-browser", "params": { "project_name": "my-project", "url": "https://example.com" } }
• 操作浏览器：执行浏览器交互的自然语言指令
  { "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." } }
• 关闭浏览器：终止浏览器实例
  { "jsonrpc": "2.0", "id": 4, "method": "mcp__browser-operator__close-browser", "params": { "project_name": "my-project" } }

作业管理

• 获取作业状态：通过作业 ID 检索操作的状态和结果
  { "jsonrpc": "2.0", "id": 5, "method": "mcp__browser-operator__get-job-status", "params": { "job_id": "job-12345" } }
• 列出作业：查看最近的浏览器操作作业
  { "jsonrpc": "2.0", "id": 6, "method": "mcp__browser-operator__list-jobs", "params": { "limit": 10 } }

用户备注

• 添加注释：创建并存储与浏览器操作相关的注释
  { "jsonrpc": "2.0", "id": 7, "method": "mcp__browser-operator__add-note", "params": { "name": "My Note", "content": "Important information about this browser session" } }

其他方法

浏览器调试工具

• 获取控制台日志： mcp__browser-tools__getConsoleLogs
• 获取控制台错误： mcp__browser-tools__getConsoleErrors
• 获取网络日志： mcp__browser-tools__getNetworkLogs
• 获取网络错误： mcp__browser-tools__getNetworkErrors
• 截屏： mcp__browser-tools__takeScreenshot
• 获取选定元素： mcp__browser-tools__getSelectedElement
• 擦除日志： mcp__browser-tools__wipeLogs

审计工具

• 运行可访问性审核： mcp__browser-tools__runAccessibilityAudit
• 运行性能审计： mcp__browser-tools__runPerformanceAudit
• 运行 SEO 审核： mcp__browser-tools__runSEOAudit
• 运行 NextJS 审计： mcp__browser-tools__runNextJSAudit
• 运行最佳实践审核： mcp__browser-tools__runBestPracticesAudit
• 运行调试器模式： mcp__browser-tools__runDebuggerMode
• 运行审核模式： mcp__browser-tools__runAuditMode

异步工作流模式

浏览器操作是异步的，并使用基于作业的方法：

1. 开始操作：调用返回 job_id 的浏览器方法
2. 轮询完成情况：使用 get-job-status 直到作业完成
3. 处理结果：作业完成时，从作业状态访问结果

这种方法可以防止客户端超时，同时允许复杂的浏览器操作完成。

持久浏览器状态

当使用项目名称创建浏览器时，MCP Operator 会维持持久状态：

• 浏览器状态（cookie、本地存储、会话存储）在会话之间保留
• 多个项目可以维护独立的浏览器状态
• 对于维护登录会话、购物车或其他个性化状态很有用

项目结构

• src/mcp_operator/ ：主包
  • __init__.py ：包初始化
  • __main__.py ：包的入口点
  • server.py ：MCP 服务器实现
  • browser.py ：浏览器操作符实现
  • cua/ ：计算机使用 API 组件
    • agent.py ：代理实现
    • computer.py ：计算机接口
    • utils.py ：实用函数
• run-server ：运行 MCP 服务器的脚本
• run-tests ：运行单元和集成测试的脚本
• run-test-harness ：使用 MCP Inspector 运行的脚本

发展

使用 MCP 检查器

如需调试，请使用MCP Inspector ：

这提供了一个 Web 界面来测试您的 MCP 服务器。

安全

• 阻止潜在有害网站的域名
• 导航前的 URL 验证
• 不同浏览器实例之间的会话隔离
• 基于文件的日志记录（没有标准输出来保留 MCP 协议）